dify/api/openapi/markdown/web-openapi.md

Web API

Public APIs for web applications including file uploads, chat interactions, and app management

Version: 1.0

Available authorizations

Bearer (HTTP, bearer)

Use the Service API key as a Bearer token in the Authorization header. Bearer format: API_KEY

---

web

Web application API operations

[POST] /audio-to-text

Convert audio to text

Convert audio file to text using speech-to-text service.

Responses

Code	Description	Schema
200	Success	application/json: AudioToTextResponse
400	Bad Request	application/json: AppUnavailableError CompletionRequestError ModelCurrentlyNotSupportError NoAudioUploadedError ProviderNotInitializeError ProviderNotSupportSpeechToTextError ProviderQuotaExceededError SpeechToTextDisabledError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
413	Audio file too large	application/json: AudioTooLargeError ErrorResponse
415	Unsupported audio type	application/json: UnsupportedAudioTypeError ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /chat-messages

Create a chat message for conversational applications.

Request Body

Required	Schema
Yes	application/json: ChatMessagePayload

Responses

Code	Description	Schema
200	Success	application/json: GeneratedAppResponse
400	Bad Request	application/json: AgentNotPublishedError AppUnavailableError CompletionRequestError ModelCurrentlyNotSupportError NotChatAppError ProviderNotInitializeError ProviderQuotaExceededError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	App Not Found	application/json: ErrorResponse
429	Too Many Requests	application/json: RateLimitError ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /chat-messages/{task_id}/stop

Stop a running chat message task.

Parameters

Name	Located in	Description	Required	Schema
task_id	path	Task ID to stop	Yes	string

Responses

Code	Description	Schema
200	Success	application/json: SimpleResultResponse
400	Bad Request	application/json: NotChatAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	Task Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /completion-messages

Create a completion message for text generation applications.

Request Body

Required	Schema
Yes	application/json: CompletionMessagePayload

Responses

Code	Description	Schema
200	Success	application/json: GeneratedAppResponse
400	Bad Request	application/json: AppUnavailableError CompletionRequestError ModelCurrentlyNotSupportError NotCompletionAppError ProviderNotInitializeError ProviderQuotaExceededError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	App Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /completion-messages/{task_id}/stop

Stop a running completion message task.

Parameters

Name	Located in	Description	Required	Schema
task_id	path	Task ID to stop	Yes	string

Responses

Code	Description	Schema
200	Success	application/json: SimpleResultResponse
400	Bad Request	application/json: NotCompletionAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	Task Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /conversations

Retrieve paginated list of conversations for a chat application.

Parameters

Name	Located in	Description	Required	Schema
last_id	query		No	string
limit	query		No	integer, Default: 20
pinned	query		No	boolean
sort_by	query		No	string, Available values: "-created_at", "-updated_at", "created_at", "updated_at", Default: -updated_at

Responses

Code	Description	Schema
200	Success	application/json: ConversationInfiniteScrollPagination
400	Invalid conversation list query or app mode does not match the API route.	application/json: NotChatAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	conversation_cursor_not_found: Cursor is outside the current list. conversation_not_found: The app or user is no longer available.	application/json: ConversationCursorNotFoundError ConversationNotFoundError ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[DELETE] /conversations/{c_id}

Delete a specific conversation.

Parameters

Name	Located in	Description	Required	Schema
c_id	path	Conversation UUID	Yes	string (uuid)

Responses

Code	Description	Schema
204	Conversation deleted successfully
400	Bad Request	application/json: NotChatAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	conversation_not_found: Conversation does not exist for this user and app.	application/json: ConversationNotFoundError ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /conversations/{c_id}/name

Rename a specific conversation with a custom name or auto-generate one.

Parameters

Name	Located in	Description	Required	Schema
c_id	path	Conversation UUID	Yes	string (uuid)
auto_generate	query	Auto-generate conversation name	No	boolean
name	query	New conversation name	No	string

Request Body

Required	Schema
Yes	application/json: ConversationRenamePayload

Responses

Code	Description	Schema
200	Conversation renamed successfully; model failure preserves the existing name.	application/json: SimpleConversation
400	Bad Request	application/json: NotChatAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	conversation_not_found: Conversation does not exist. conversation_first_message_not_found: No first message is available for automatic naming.	application/json: ConversationFirstMessageNotFoundError ConversationNotFoundError ErrorResponse
422	Invalid conversation rename payload.	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[PATCH] /conversations/{c_id}/pin

Pin a specific conversation to keep it at the top of the list.

Parameters

Name	Located in	Description	Required	Schema
c_id	path	Conversation UUID	Yes	string (uuid)

Responses

Code	Description	Schema
200	Conversation pinned successfully	application/json: ResultResponse
400	Bad Request	application/json: NotChatAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	conversation_not_found: Conversation does not exist for this user and app.	application/json: ConversationNotFoundError ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[PATCH] /conversations/{c_id}/unpin

Remove the current user's pin. Succeeds when the conversation is already unpinned.

Parameters

Name	Located in	Description	Required	Schema
c_id	path	Conversation UUID	Yes	string (uuid)

Responses

Code	Description	Schema
200	Conversation unpinned successfully	application/json: ResultResponse
400	Bad Request	application/json: NotChatAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	conversation_not_found: The app or user is no longer available.	application/json: ConversationNotFoundError ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /email-code-login

Send email verification code for login

Request Body

Required	Schema
Yes	application/json: EmailCodeLoginSendPayload

Responses

Code	Description	Schema
200	Email code sent successfully	application/json: SimpleResultDataResponse
400	Bad request - invalid email format	application/json: ErrorResponse
401	Unauthorized	application/json: AuthenticationFailedError ErrorResponse
404	Account not found	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /email-code-login/validity

Verify email code and complete login

Request Body

Required	Schema
Yes	application/json: EmailCodeLoginVerifyPayload

Responses

Code	Description	Schema
200	Email code verified and login successful	application/json: AccessTokenResultResponse
400	Bad request - invalid code or token	application/json: AccountBannedError EmailCodeError InvalidEmailError ErrorResponse
401	Invalid token or expired code	application/json: AuthenticationFailedError ErrorResponse
404	Account not found	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /files/upload

Upload a file for use in web applications

Upload a file for use in web applications Accepts file uploads for use within web applications, supporting multiple file types with automatic validation and storage.

Args: app_model: The associated application model end_user: The end user uploading the file

Form Parameters: file: The file to upload (required) source: Optional source type (datasets or None)

Returns: dict: File information including ID, URL, and metadata int: HTTP status code 201 for success

Raises: NoFileUploadedError: No file provided in request TooManyFilesError: Multiple files provided (only one allowed) FilenameNotExistsError: File has no filename FileTooLargeError: File exceeds size limit UnsupportedFileTypeError: File type not supported BlockedFileExtensionError: File extension is blocked

Responses

Code	Description	Schema
201	File uploaded successfully	application/json: FileResponse
400	- no_file_uploaded : No file was provided in the request. - too_many_files : Only one file is allowed per request. - filename_not_exists_error : The uploaded file has no filename. - file_extension_blocked : The file extension is blocked for security reasons.	application/json: FileExtensionBlockedError FilenameNotExistsError NoFileUploadedError TooManyFilesError ErrorResponse
413	file_too_large : File size exceeded.	application/json: FileTooLargeError ErrorResponse
415	unsupported_file_type : File type not allowed.	application/json: UnsupportedFileTypeError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /forgot-password

Send password reset email

Request Body

Required	Schema
Yes	application/json: ForgotPasswordSendPayload

Responses

Code	Description	Schema
200	Password reset email sent successfully	application/json: SimpleResultDataResponse
400	Bad request - invalid email format	application/json: ErrorResponse
401	Unauthorized	application/json: AuthenticationFailedError ErrorResponse
404	Account not found	application/json: ErrorResponse
429	Too many requests - rate limit exceeded	application/json: EmailSendIpLimitError PasswordResetRateLimitExceededError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /forgot-password/resets

Reset user password with verification token

Request Body

Required	Schema
Yes	application/json: ForgotPasswordResetPayload

Responses

Code	Description	Schema
200	Password reset successfully	application/json: SimpleResultResponse
400	Bad request - invalid parameters or password mismatch	application/json: InvalidOrExpiredTokenError PasswordMismatchError ErrorResponse
401	Invalid or expired token	application/json: AuthenticationFailedError ErrorResponse
404	Account not found	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /forgot-password/validity

Verify password reset token validity

Request Body

Required	Schema
Yes	application/json: ForgotPasswordCheckPayload

Responses

Code	Description	Schema
200	Token is valid	application/json: VerificationTokenResponse
400	Bad request - invalid token format	application/json: EmailCodeError InvalidEmailError InvalidOrExpiredTokenError ErrorResponse
401	Invalid or expired token	application/json: ErrorResponse
429	Too Many Requests	application/json: EmailPasswordResetLimitError ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /form/human-input/v2/public/{form_token}

Read a public v2 form definition by delivery token without an OTP or login session.

Parameters

Name	Located in	Description	Required	Schema
form_token	path		Yes	string

Responses

Code	Description	Schema
200	Form definition	application/json: FormDefinitionResponse
404	Form not found	application/json: HumanInputFormNotFoundError ErrorResponse
412	Form already submitted or expired	application/json: HumanInputFormExpiredError HumanInputFormSubmittedError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /form/human-input/v2/public/{form_token}

Submit a form with inputs, an action, and email verification proof.

Parameters

Name	Located in	Description	Required	Schema
form_token	path		Yes	string

Request Body

Required	Schema
Yes	application/json: HumanInputV2FormSubmitRequest

Responses

Code	Description	Schema
200	Form submitted	application/json: FormSubmitResponse
400	Invalid form or email proof	application/json: HumanInputChallengeExpiredError HumanInputChallengeStaleError HumanInputInvalidOtpError InvalidInputError ErrorResponse
404	Form not found	application/json: HumanInputFormNotFoundError ErrorResponse
409	Workflow not active	application/json: WorkflowNotActiveError ErrorResponse
412	Already submitted or expired	application/json: HumanInputFormExpiredError HumanInputFormSubmittedError ErrorResponse
422	Invalid request body	application/json: ErrorResponse
503	Email verification unavailable	application/json: HumanInputV2UnavailableError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /form/human-input/v2/public/{form_token}/access-request

Parameters

Name	Located in	Description	Required	Schema
form_token	path		Yes	string

Responses

Code	Description	Schema
200	Success	application/json: FormAccessRequestResponse
404	Not Found	application/json: HumanInputFormNotFoundError ErrorResponse
412	Precondition Failed	application/json: HumanInputFormExpiredError HumanInputFormSubmittedError ErrorResponse
429	Too Many Requests	application/json: HumanInputAccessRateLimitExceededError ErrorResponse
503	Service Unavailable	application/json: HumanInputAccessDeliveryFailedError HumanInputV2UnavailableError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /form/human-input/v2/public/{form_token}/upload-token

Parameters

Name	Located in	Description	Required	Schema
form_token	path		Yes	string

Responses

Code	Description	Schema
200	Success	application/json: FormUploadTokenResponse
403	Forbidden	application/json: InvalidUploadTokenError ErrorResponse
404	Form not found	application/json: HumanInputFormNotFoundError ErrorResponse
412	Already submitted or expired	application/json: HumanInputFormExpiredError HumanInputFormSubmittedError ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /form/human-input/v2/{form_token}

Read a v2 form using the original EndUser's Web App passport.

Parameters

Name	Located in	Description	Required	Schema
form_token	path		Yes	string

Responses

Code	Description	Schema
200	Form retrieved	application/json: WebAppHumanInputV2FormDefinitionResponse
401	Invalid passport	application/json: ErrorResponse
404	Form not found	application/json: ErrorResponse
409	Already submitted	application/json: AlreadySubmittedError ErrorResponse
410	Expired	application/json: ExpiredError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /form/human-input/v2/{form_token}

Submit a v2 form using the original EndUser's Web App passport.

Parameters

Name	Located in	Description	Required	Schema
form_token	path		Yes	string

Request Body

Required	Schema
Yes	application/json: WebAppHumanInputV2SubmitPayload

Responses

Code	Description	Schema
200	Approval accepted	application/json: WebAppHumanInputV2SubmitResponse
400	Invalid inputs	application/json: InvalidInputError ErrorResponse
401	Invalid passport	application/json: ErrorResponse
404	Form not found	application/json: ErrorResponse
409	Already submitted or workflow not active	application/json: AlreadySubmittedError WorkflowNotActiveError ErrorResponse
410	Expired	application/json: ExpiredError ErrorResponse
422	Invalid request body	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /form/human_input/{form_token}

Get human input form definition by token

Get a human input form definition by token GET /api/form/human_input/<form_token>

Parameters

Name	Located in	Description	Required	Schema
form_token	path	Human input form token	Yes	string

Responses

Code	Description	Schema
200	Form retrieved successfully	application/json: HumanInputFormDefinitionResponse
403	Forbidden	application/json: ErrorResponse
404	Form not found	application/json: ErrorResponse
412	Form already submitted or expired	application/json: HumanInputFormExpiredError HumanInputFormSubmittedError ErrorResponse
429	Too many requests	application/json: WebFormRateLimitExceededError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /form/human_input/{form_token}

Submit human input form by token

Submit a human input form by token POST /api/form/human_input/<form_token>

Request body: { "inputs": { "content": "User input content" }, "action": "Approve" }

Parameters

Name	Located in	Description	Required	Schema
form_token	path	Human input form token	Yes	string

Request Body

Required	Schema
Yes	application/json: HumanInputFormSubmitPayload

Responses

Code	Description	Schema
200	Form submitted successfully	application/json: HumanInputFormSubmitResponse
400	Bad request - invalid submission data	application/json: InvalidFormDataError ErrorResponse
404	Form not found	application/json: ErrorResponse
412	Form already submitted or expired	application/json: HumanInputFormExpiredError HumanInputFormSubmittedError ErrorResponse
429	Too many requests	application/json: WebFormRateLimitExceededError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /form/human_input/{form_token}/upload-token

Issue an upload token for a human input form

Issue an upload token for an active human input form POST /api/form/human_input/<form_token>/upload-token

Parameters

Name	Located in	Description	Required	Schema
form_token	path	Human input form token	Yes	string

Responses

Code	Description	Schema
200	Upload token issued successfully	application/json: HumanInputUploadTokenResponse
404	Form not found	application/json: ErrorResponse
412	Form already submitted or expired	application/json: HumanInputFormExpiredError HumanInputFormSubmittedError ErrorResponse
429	Too many requests	application/json: WebFormRateLimitExceededError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /human-input-forms/files

Upload one local file or remote URL file for a HITL human input form

Responses

Code	Description	Schema
201	File uploaded successfully	application/json: FileResponse
400	Bad Request	application/json: FileExtensionBlockedError FilenameNotExistsError MalformedUploadTokenError NoFileUploadedError RemoteFileAccessDeniedError RemoteFileInvalidUrlError RemoteFileUrlBlockedError TooManyFilesError ErrorResponse
401	Unauthorized	application/json: UploadTokenRequiredError ErrorResponse
403	Forbidden	application/json: InvalidUploadTokenError ErrorResponse
404	Not Found	application/json: RemoteFileNotFoundError ErrorResponse
412	Precondition Failed	application/json: HumanInputFormExpiredError HumanInputFormSubmittedError ErrorResponse
413	Request Entity Too Large	application/json: FileTooLargeError ErrorResponse
415	Unsupported Media Type	application/json: UnsupportedFileTypeError ErrorResponse
502	Bad Gateway	application/json: RemoteFileInvalidResponseError RemoteFileUnavailableError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /human-input/v2/files

Upload a file or a remote URL using a v2 upload grant.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header	Bearer v2 upload grant	Yes	string

Request Body

Required	Schema
No	multipart/form-data: { "file": binary, "url": string }

Responses

Code	Description	Schema
201	File uploaded	application/json: FileWithSignedUrl
400	Invalid upload	application/json: FileExtensionBlockedError FilenameNotExistsError MalformedUploadTokenError NoFileUploadedError RemoteFileAccessDeniedError RemoteFileInvalidUrlError RemoteFileUrlBlockedError TooManyFilesError ErrorResponse
401	Grant required	application/json: UploadTokenRequiredError ErrorResponse
403	Invalid grant	application/json: InvalidUploadTokenError ErrorResponse
404	Form not found	application/json: HumanInputFormNotFoundError RemoteFileNotFoundError ErrorResponse
412	Form inactive	application/json: HumanInputFormExpiredError HumanInputFormSubmittedError ErrorResponse
413	Request Entity Too Large	application/json: FileTooLargeError ErrorResponse
415	Unsupported Media Type	application/json: UnsupportedFileTypeError ErrorResponse
502	Bad Gateway	application/json: RemoteFileInvalidResponseError RemoteFileUnavailableError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /human-input/v2/files/remote

Fetch a remote file using a v2 upload grant.

Parameters

Name	Located in	Description	Required	Schema
Authorization	header		Yes	string

Request Body

Required	Schema
Yes	application/json: HumanInputV2RemoteUploadPayload

Responses

Code	Description	Schema
201	File uploaded	application/json: FileWithSignedUrl
400	Invalid upload	application/json: FileExtensionBlockedError FilenameNotExistsError MalformedUploadTokenError NoFileUploadedError RemoteFileAccessDeniedError RemoteFileInvalidUrlError RemoteFileUrlBlockedError TooManyFilesError ErrorResponse
401	Grant required	application/json: UploadTokenRequiredError ErrorResponse
403	Invalid grant	application/json: InvalidUploadTokenError ErrorResponse
404	Form not found	application/json: HumanInputFormNotFoundError RemoteFileNotFoundError ErrorResponse
412	Form inactive	application/json: HumanInputFormExpiredError HumanInputFormSubmittedError ErrorResponse
413	Request Entity Too Large	application/json: FileTooLargeError ErrorResponse
415	Unsupported Media Type	application/json: UnsupportedFileTypeError ErrorResponse
502	Bad Gateway	application/json: RemoteFileInvalidResponseError RemoteFileUnavailableError ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /login

Authenticate user and login

Authenticate user for web application access

Request Body

Required	Schema
Yes	application/json: LoginPayload

Responses

Code	Description	Schema
200	Authentication successful	application/json: AccessTokenResultResponse
400	Bad request - invalid email or password format	application/json: AccountBannedError ErrorResponse
401	Authentication failed - email or password mismatch	application/json: AuthenticationFailedError ErrorResponse
404	Account not found	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /login/status

Check login status

Parameters

Name	Located in	Description	Required	Schema
app_code	query	Web app code	No	string
user_id	query	End user session ID	No	string

Responses

Code	Description	Schema
200	Login status	application/json: LoginStatusResponse
401	Login status	application/json: ErrorResponse
404	App not found	application/json: ErrorResponse
503	Web app access service unavailable	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /logout

Logout user from web application

Responses

Code	Description	Schema
200	Logout successful	application/json: SimpleResultResponse
default	Error	application/json: ErrorResponse

[GET] /messages

Retrieve paginated list of messages from a conversation in a chat application.

Parameters

Name	Located in	Description	Required	Schema
conversation_id	query	Conversation ID.	Yes	string
first_id	query	The ID of the first chat record on the current page. Omit this value to fetch the latest messages; for subsequent pages, use the first message ID from the current list to fetch older messages.	No	string
limit	query	Number of chat history messages to return per request.	No	integer, Default: 20

Responses

Code	Description	Schema
200	Success	application/json: WebMessageInfiniteScrollPagination
400	Bad Request - Not a chat app or app unavailable	application/json: AppUnavailableError NotChatAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	Conversation, First Message, or End User Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /messages/{message_id}/feedbacks

Submit feedback (like/dislike) for a specific message.

Parameters

Name	Located in	Description	Required	Schema
message_id	path	Message UUID	Yes	string (uuid)
content	query	Feedback content	No	string
rating	query	Feedback rating	No	string, Available values: "dislike", "like"

Request Body

Required	Schema
Yes	application/json: MessageFeedbackPayload

Responses

Code	Description	Schema
200	Feedback submitted successfully	application/json: ResultResponse
400	message_feedback_rating_required: Cannot revoke feedback that does not exist. app_unavailable: App is no longer available.	application/json: AppUnavailableError MessageFeedbackRatingRequiredError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
403	Forbidden	application/json: ErrorResponse
404	Message Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /messages/{message_id}/more-like-this

Generate a new completion similar to an existing message (completion apps only).

Parameters

Name	Located in	Description	Required	Schema
response_mode	query	Response mode	Yes	string, Available values: "blocking", "streaming"
message_id	path		Yes	string (uuid)

Responses

Code	Description	Schema
200	Success	application/json: GeneratedAppResponse
400	Bad Request - Not a completion app, app unavailable, or model invocation failed	application/json: AppUnavailableError CompletionRequestError ModelCurrentlyNotSupportError NotCompletionAppError ProviderNotInitializeError ProviderQuotaExceededError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
403	Forbidden - Access denied or more-like-this disabled	application/json: AppMoreLikeThisDisabledError ErrorResponse
404	Message Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /messages/{message_id}/suggested-questions

Get suggested follow-up questions after a message (chat apps only). If no usable model can be resolved or the model call to generate questions fails, the response is HTTP 200 with an empty data list. Model invocation failures during history token counting instead return HTTP 400 with completion_request_error.

Parameters

Name	Located in	Description	Required	Schema
message_id	path	Message UUID	Yes	string (uuid)

Responses

Code	Description	Schema
200	Success	application/json: SuggestedQuestionsResponse
400	Bad Request - Not a chat app or app unavailable; completion_request_error when model invocation fails while counting history tokens.	application/json: AppUnavailableError CompletionRequestError ModelCurrentlyNotSupportError NotChatAppError ProviderNotInitializeError ProviderQuotaExceededError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
403	Forbidden - Access denied or suggested questions disabled	application/json: AppSuggestedQuestionsAfterAnswerDisabledError ErrorResponse
404	App, End User, Message, or Conversation Not Found	application/json: AgentVersionNotFoundError ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /meta

Get app meta

Retrieve the metadata for a specific app.

Responses

Code	Description	Schema
200	Success	application/json: AppMetaResponse
400	Bad Request	application/json: AppUnavailableError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	App Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /parameters

Retrieve app parameters

Retrieve the parameters for a specific app.

Responses

Code	Description	Schema
200	Success	application/json: Parameters
400	Bad Request	application/json: AgentNotPublishedError AppUnavailableError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	App Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /passport

Get authentication passport for web application access

Parameters

Name	Located in	Description	Required	Schema
user_id	query	End user session ID	No	string

Responses

Code	Description	Schema
200	Passport retrieved successfully	application/json: PassportAccessTokenResponse
401	Unauthorized - missing app code or invalid authentication	application/json: ErrorResponse
404	Application or user not found	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /remote-files/upload

Upload a file from a remote URL

Upload a file from a remote URL Downloads a file from the provided remote URL and uploads it to the platform storage for use in web applications.

Args: app_model: The associated application model end_user: The end user making the request

JSON Parameters: url: The remote URL to download the file from (required)

Returns: dict: File information including ID, signed URL, and metadata int: HTTP status code 201 for success

Raises: RemoteFileInvalidUrlError: Remote file URL is invalid RemoteFileUrlBlockedError: Remote file URL is blocked RemoteFileNotFoundError: Remote file does not exist RemoteFileAccessDeniedError: Remote file requires authorization RemoteFileUnavailableError: Remote file is unavailable RemoteFileInvalidResponseError: Remote file response is invalid FileTooLargeError: File exceeds size limit UnsupportedFileTypeError: File type not supported

Request Body

Required	Schema
Yes	application/json: RemoteFileUploadPayload

Responses

Code	Description	Schema
201	Remote file uploaded successfully	application/json: FileWithSignedUrl
400	Invalid, blocked, or inaccessible remote file URL	application/json: FileExtensionBlockedError RemoteFileAccessDeniedError RemoteFileInvalidUrlError RemoteFileUrlBlockedError ErrorResponse
404	Remote file not found	application/json: RemoteFileNotFoundError ErrorResponse
413	File too large	application/json: FileTooLargeError ErrorResponse
415	Unsupported file type	application/json: UnsupportedFileTypeError ErrorResponse
422	Request payload validation failed	application/json: ErrorResponse
500	Internal server error	application/json: ErrorResponse
502	Remote file unavailable or returned an invalid response	application/json: RemoteFileInvalidResponseError RemoteFileUnavailableError ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /remote-files/{url}

Get information about a remote file

Get information about a remote file Retrieves basic information about a file located at a remote URL, including content type and content length.

Args: app_model: The associated application model end_user: The end user making the request url: URL-encoded path to the remote file

Returns: dict: Remote file information including type and length

Raises: HTTPException: If the remote file cannot be accessed

Parameters

Name	Located in	Description	Required	Schema
url	path		Yes	string

Responses

Code	Description	Schema
200	Remote file information retrieved successfully	application/json: RemoteFileInfo
400	Invalid, blocked, or inaccessible remote file URL	application/json: RemoteFileAccessDeniedError RemoteFileInvalidUrlError RemoteFileUrlBlockedError ErrorResponse
404	Remote file not found	application/json: RemoteFileNotFoundError ErrorResponse
500	Internal server error	application/json: ErrorResponse
502	Remote file unavailable or returned an invalid response	application/json: RemoteFileInvalidResponseError RemoteFileUnavailableError ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /saved-messages

Retrieve paginated list of saved messages for a completion application.

Parameters

Name	Located in	Description	Required	Schema
last_id	query		No	string
limit	query		No	integer, Default: 20

Responses

Code	Description	Schema
200	Success	application/json: SavedMessageInfiniteScrollPagination
400	Bad Request - Not a completion app	application/json: NotCompletionAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	App Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /saved-messages

Save a specific message for later reference.

Parameters

Name	Located in	Description	Required	Schema
message_id	query	Message UUID to save	Yes	string

Request Body

Required	Schema
Yes	application/json: SavedMessageCreatePayload

Responses

Code	Description	Schema
200	Message saved successfully	application/json: ResultResponse
400	Bad Request - Not a completion app	application/json: NotCompletionAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	Message Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[DELETE] /saved-messages/{message_id}

Remove a message from saved messages.

Parameters

Name	Located in	Description	Required	Schema
message_id	path	Message UUID to delete	Yes	string (uuid)

Responses

Code	Description	Schema
204	Message removed successfully
400	Bad Request - Not a completion app	application/json: NotCompletionAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	Message Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /site

Retrieve app site info

Retrieve app site information and configuration.

Responses

Code	Description	Schema
200	Success	application/json: WebAppSiteResponse
400	Bad Request	application/json: ErrorResponse
401	Unauthorized	application/json: ErrorResponse
403	Forbidden	application/json: ErrorResponse
404	App Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /system-features

Get the non-sensitive bootstrap snapshot exposed before authentication

Get the non-sensitive bootstrap snapshot exposed before Console or Web authentication. This is not a general feature registry. This endpoint is akin to the SystemFeatureApi endpoint in api/controllers/console/feature.py, except it is intended for use by the web app, instead of the console dashboard.

Authentication configuration must be available before the authentication flow can be selected.

Responses

Code	Description	Schema
200	System features retrieved successfully	application/json: SystemFeatureModel
500	Internal server error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /text-to-audio

Convert text to audio

Convert text to audio using text-to-speech service.

Request Body

Required	Schema
Yes	application/json: TextToAudioPayload

Responses

Code	Description	Schema
200	Success
400	Bad Request	application/json: AppUnavailableError CompletionRequestError ModelCurrentlyNotSupportError ProviderNotInitializeError ProviderQuotaExceededError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /webapp/access-mode

Retrieve the access mode for a web application (public or restricted).

Parameters

Name	Located in	Description	Required	Schema
appCode	query	Application code	No	string
appId	query	Application ID	No	string

Responses

Code	Description	Schema
200	Success	application/json: AccessModeResponse
400	Bad Request	application/json: InvalidParamError ErrorResponse
404	App Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
503	Web App Access Service Unavailable	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[GET] /webapp/permission

Check if user has permission to access a web application.

Parameters

Name	Located in	Description	Required	Schema
appId	query	Application ID	Yes	string

Responses

Code	Description	Schema
200	Success	application/json: BooleanResultResponse
400	Bad Request	application/json: ErrorResponse
401	Unauthorized	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
503	Web App Access Service Unavailable	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /workflows/run

Run workflow

Execute a workflow with provided inputs and files.

Request Body

Required	Schema
Yes	application/json: WorkflowRunPayload

Responses

Code	Description	Schema
200	Success	application/json: GeneratedAppResponse
400	Bad Request	application/json: CompletionRequestError ModelCurrentlyNotSupportError NotWorkflowAppError ProviderNotInitializeError ProviderQuotaExceededError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
403	Forbidden	application/json: TriggerWorkflowServiceModeUnavailableError ErrorResponse
404	App Not Found	application/json: ErrorResponse
429	Too Many Requests	application/json: RateLimitError ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

[POST] /workflows/tasks/{task_id}/stop

Stop workflow task

Stop a running workflow task.

Parameters

Name	Located in	Description	Required	Schema
task_id	path	Task ID to stop	Yes	string

Responses

Code	Description	Schema
200	Success	application/json: SimpleResultResponse
400	Bad Request	application/json: NotWorkflowAppError ErrorResponse
401	Unauthorized	application/json: ErrorResponse
404	Task Not Found	application/json: ErrorResponse
500	Internal Server Error	application/json: ErrorResponse
default	Error	application/json: ErrorResponse

---

default

Default namespace

[GET] /workflow/{task_id}/events

Get workflow execution events stream after resume

GET /api/workflow/<task_id>/events

Returns Server-Sent Events stream.

Parameters

Name	Located in	Description	Required	Schema
task_id	path		Yes	string

Responses

Code	Description	Schema
200	SSE event stream	application/json: EventStreamResponse
400	Bad Request	application/json: InvalidParamError ErrorResponse
default	Error	application/json: ErrorResponse

---

Schemas

AccessModeResponse

Name	Type	Description	Required
accessMode	string		Yes

AccessTokenData

Name	Type	Description	Required
access_token	string		Yes

AccessTokenResultResponse

Name	Type	Description	Required
data	AccessTokenData		Yes
result	string		Yes

AccountBannedError

Account is banned.

Name	Type	Description	Required
AccountBannedError		Account is banned.

AgentNotPublishedError

Agent has not been published. Please publish the Agent before using the web app.

Name	Type	Description	Required
AgentNotPublishedError		Agent has not been published. Please publish the Agent before using the web app.

AgentThought

Name	Type	Description	Required
answer	string		No
chain_id	string		No
created_at	integer		No
files	[ string ]		Yes
id	string		Yes
message_id	string		Yes
observation	string		No
position	integer		Yes
thought	string		No
tool	string		No
tool_input	string		No
tool_labels	AnyJSONValue	Labels for tools used.	Yes

AgentVersionNotFoundError

Agent config version not found.

Name	Type	Description	Required
AgentVersionNotFoundError		Agent config version not found.

AlreadySubmittedError

Name	Type	Description	Required
AlreadySubmittedError

AnyJSONValue

Name	Type	Description	Required
AnyJSONValue

AppAccessModeQuery

Name	Type	Description	Required
appCode	string	Application code	No
appId	string	Application ID	No

AppMetaResponse

Name	Type	Description	Required
tool_icons	object	Tool icon metadata keyed by tool name	No

AppMode

Name	Type	Description	Required
AppMode	string

AppMoreLikeThisDisabledError

The 'More like this' feature is disabled. Please refresh your page.

Name	Type	Description	Required
AppMoreLikeThisDisabledError		The 'More like this' feature is disabled. Please refresh your page.

AppPermissionQuery

Name	Type	Description	Required
appId	string	Application ID	Yes

AppSuggestedQuestionsAfterAnswerDisabledError

The 'Suggested Questions After Answer' feature is disabled. Please refresh your page.

Name	Type	Description	Required
AppSuggestedQuestionsAfterAnswerDisabledError		The 'Suggested Questions After Answer' feature is disabled. Please refresh your page.

AppUnavailableError

App unavailable, please check your app configurations.

Name	Type	Description	Required
AppUnavailableError		App unavailable, please check your app configurations.

AudioToTextResponse

Name	Type	Description	Required
text	string		Yes

AudioTooLargeError

Audio size exceeded. {message}

Name	Type	Description	Required
AudioTooLargeError		Audio size exceeded. {message}

AuthenticationFailedError

Invalid email or password.

Name	Type	Description	Required
AuthenticationFailedError		Invalid email or password.

BooleanResultResponse

Name	Type	Description	Required
result	boolean		Yes

BrandingModel

Name	Type	Description	Required
application_title	string		Yes
enabled	boolean		Yes
favicon	string		Yes
login_page_logo	string		Yes
workspace_logo	string		Yes

ButtonStyle

Button styles for user actions.

Name	Type	Description	Required
ButtonStyle	string	Button styles for user actions.

ChatMessagePayload

Name	Type	Description	Required
conversation_id	string	Conversation ID	No
files	[ object ]	Files to be processed	No
inputs	object	Input variables for the chat	Yes
parent_message_id	string	Parent message ID	No
query	string	User query/message	Yes
response_mode	string, Available values: "blocking", "streaming"	Response mode: blocking or streaming	No
retriever_from	string, Default: web_app	Source of retriever	No

CompletionMessagePayload

Name	Type	Description	Required
files	[ object ]	Files to be processed	No
inputs	object	Input variables for the completion	Yes
query	string	Query text for completion	No
response_mode	string, Available values: "blocking", "streaming"	Response mode: blocking or streaming	No
retriever_from	string, Default: web_app	Source of retriever	No

CompletionRequestError

Completion request failed.

Name	Type	Description	Required
CompletionRequestError		Completion request failed.

ConversationCursorNotFoundError

The conversation cursor is not in the current list. Refresh the list and try again.

Name	Type	Description	Required
ConversationCursorNotFoundError		The conversation cursor is not in the current list. Refresh the list and try again.

ConversationFirstMessageNotFoundError

The conversation has no message from which to generate a name.

Name	Type	Description	Required
ConversationFirstMessageNotFoundError		The conversation has no message from which to generate a name.

ConversationInfiniteScrollPagination

Name	Type	Description	Required
data	[ SimpleConversation ]		Yes
has_more	boolean		Yes
limit	integer		Yes

ConversationListQuery

Name	Type	Description	Required
last_id	string		No
limit	integer, Default: 20		No
pinned	boolean		No
sort_by	string, Available values: "-created_at", "-updated_at", "created_at", "updated_at", Default: -updated_at	Enum: "-created_at", "-updated_at", "created_at", "updated_at"	No

ConversationNotFoundError

The conversation was not found for this user and app.

Name	Type	Description	Required
ConversationNotFoundError		The conversation was not found for this user and app.

ConversationRenamePayload

Name	Type	Description	Required
auto_generate	boolean	Automatically generate the conversation name. When true, the name field is ignored.	No
name	string	Conversation name. Required when auto_generate is false.	No

DeploymentEdition

Enum representing the deployment edition of the platform.

Name	Type	Description	Required
DeploymentEdition	string	Enum representing the deployment edition of the platform.

EmailCodeError

Email code is invalid or expired.

Name	Type	Description	Required
EmailCodeError		Email code is invalid or expired.

EmailCodeLoginSendPayload

Name	Type	Description	Required
email	string		Yes
language	string		No

EmailCodeLoginVerifyPayload

Name	Type	Description	Required
code	string		Yes
email	string		Yes
token	string		Yes

EmailPasswordResetLimitError

Too many failed password reset attempts. Please try again in 24 hours.

Name	Type	Description	Required
EmailPasswordResetLimitError		Too many failed password reset attempts. Please try again in 24 hours.

EmailSendIpLimitError

Too many emails have been sent from this IP address recently. Please try again later.

Name	Type	Description	Required
EmailSendIpLimitError		Too many emails have been sent from this IP address recently. Please try again later.

ErrorResponse

Documented non-2xx body emitted by register_external_error_handlers.

params and details appear only on the errors that set them. The schema stays open because HTTPException.data may carry extra keys.

Name	Type	Description	Required
code	string		Yes
details	object		No
message	string		Yes
params	string		No
status	integer		Yes

EventStreamResponse

Name	Type	Description	Required
EventStreamResponse	string

ExecutionContentType

Name	Type	Description	Required
ExecutionContentType	string

ExpiredError

Name	Type	Description	Required
ExpiredError

FileExtensionBlockedError

The file extension is blocked for security reasons.

Name	Type	Description	Required
FileExtensionBlockedError		The file extension is blocked for security reasons.

FileInput

Resolved single-file input constraints.

Name	Type	Description	Required
allowed_file_extensions	[ string ]		Yes
allowed_file_types	[ FileType ]		Yes
allowed_file_upload_methods	[ FileTransferMethod ]		Yes
output_variable_name	string		Yes
type	string		No

FileInputConfig

Name	Type	Description	Required
allowed_file_extensions	[ string ]		No
allowed_file_types	[ FileType ]		No
allowed_file_upload_methods	[ FileTransferMethod ]		No
output_variable_name	string		Yes
type	string		No

FileListInput

Resolved multi-file input constraints and effective number limit.

Name	Type	Description	Required
allowed_file_extensions	[ string ]		Yes
allowed_file_types	[ FileType ]		Yes
allowed_file_upload_methods	[ FileTransferMethod ]		Yes
number_limits	integer		Yes
output_variable_name	string		Yes
type	string		No

FileListInputConfig

Name	Type	Description	Required
allowed_file_extensions	[ string ]		No
allowed_file_types	[ FileType ]		No
allowed_file_upload_methods	[ FileTransferMethod ]		No
number_limits	integer		No
output_variable_name	string		Yes
type	string		No

FileResponse

Name	Type	Description	Required
conversation_id	string		No
created_at	integer		No
created_by	string		No
extension	string		No
file_key	string		No
id	string (uuid)		Yes
mime_type	string		No
name	string		Yes
original_url	string		No
preview_url	string		No
reference	string		No
size	integer		Yes
source_url	string		No
tenant_id	string		No
user_id	string		No

FileTooLargeError

File size exceeded. {message}

Name	Type	Description	Required
FileTooLargeError		File size exceeded. {message}

FileTransferMethod

Name	Type	Description	Required
FileTransferMethod	string

FileType

Name	Type	Description	Required
FileType	string

FileWithSignedUrl

Name	Type	Description	Required
created_at	integer		Yes
created_by	string		Yes
extension	string		Yes
id	string		Yes
mime_type	string		Yes
name	string		Yes
size	integer		Yes
url	string		Yes

FilenameNotExistsError

The specified filename does not exist.

Name	Type	Description	Required
FilenameNotExistsError		The specified filename does not exist.

ForgotPasswordCheckPayload

Name	Type	Description	Required
code	string		Yes
email	string		Yes
token	string		Yes

ForgotPasswordResetPayload

Name	Type	Description	Required
new_password	string		Yes
password_confirm	string		Yes
token	string		Yes

ForgotPasswordSendPayload

Name	Type	Description	Required
email	string		Yes
language	string		No

FormAccessRequestResponse

Response body returned after creating one OTP challenge.

Name	Type	Description	Required
challenge_token	string	The token used to complete the OTP challenge.	Yes
expires_in_seconds	integer	Seconds until the current OTP challenge expires.	Yes
resend_after_seconds	integer	Seconds until another OTP challenge may be requested.	Yes

FormDefinitionResponse

Response body containing a resolved human-input form definition.

Name	Type	Description	Required
expiration_time	integer	Unix timestamp when the current form expires.	Yes
form_content	string	Rendered form body shown to the approver.	No
inputs	[ FormInputConfig ]	Resolved form input definitions.	No
resolved_default_values	object	Default values after variable resolution and stringification.	No
user_actions	[ UserActionConfig ]	Action buttons that can complete the form.	No

FormInputConfig

Name	Type	Description	Required
FormInputConfig	ParagraphInputConfig SelectInputConfig FileInputConfig FileListInputConfig

FormPart

Name	Type	Description	Required
FormPart	MarkdownFragment ParagraphInput SelectInput FileInput FileListInput

FormSubmitResponse

Empty response body returned after a Human Input v2 form submission.

Name	Type	Description	Required

FormUploadTokenResponse

Response body returned when issuing a Human Input v2 upload token.

Name	Type	Description	Required
expires_at	integer		Yes
upload_token	string		Yes

GeneratedAppResponse

Name	Type	Description	Required
GeneratedAppResponse

HumanInputAccessDeliveryFailedError

Name	Type	Description	Required
HumanInputAccessDeliveryFailedError

HumanInputAccessRateLimitExceededError

Name	Type	Description	Required
HumanInputAccessRateLimitExceededError

HumanInputChallengeExpiredError

Name	Type	Description	Required
HumanInputChallengeExpiredError

HumanInputChallengeStaleError

Name	Type	Description	Required
HumanInputChallengeStaleError

HumanInputContent

Name	Type	Description	Required
form_definition	HumanInputFormDefinition		No
form_submission_data	HumanInputFormSubmissionData		No
submitted	boolean		Yes
type	ExecutionContentType		No
workflow_run_id	string		Yes

HumanInputFileUploadFormPayload

Parsed multipart form fields for HITL uploads.

Name	Type	Description	Required
url	string	Remote file URL	No

HumanInputFormDefinition

Name	Type	Description	Required
actions	[ UserActionConfig ]		No
display_in_ui	boolean		No
expiration_time	integer		Yes
form_content	string		Yes
form_id	string		Yes
form_token	string		No
form_version	string, Available values: "1", "2", Default: 1	Enum: "1", "2"	No
inputs	[ FormInputConfig ]		No
node_id	string		Yes
node_title	string		Yes
resolved_default_values	object		No

HumanInputFormDefinitionResponse

Name	Type	Description	Required
expiration_time	integer		Yes
form_content	string		Yes
inputs	[ FormInputConfig ]		Yes
resolved_default_values	object		Yes
site	WebAppSiteResponse		No
user_actions	[ UserActionConfig ]		Yes

HumanInputFormExpiredError

Name	Type	Description	Required
HumanInputFormExpiredError

HumanInputFormNotFoundError

Name	Type	Description	Required
HumanInputFormNotFoundError

HumanInputFormSubmissionData

Name	Type	Description	Required
action_id	string		Yes
action_text	string		Yes
node_id	string		Yes
node_title	string		Yes
rendered_content	string		Yes
submitted_data	object		No

HumanInputFormSubmitPayload

Legacy Human Input v1 submit payload shared by existing runtime surfaces.

Name	Type	Description	Required
action	string	ID of the action button the recipient selected. Must match one of the id values from the form's user_actions list.	Yes
inputs	object	Submitted human input values keyed by output variable name. Use a string for paragraph or select input values, a file mapping for file inputs, and a list of file mappings for file-list inputs. Local file mappings use transfer_method=local_file with upload_file_id; remote file mappings use transfer_method=remote_url with url or remote_url.	Yes

HumanInputFormSubmitResponse

Name	Type	Description	Required

HumanInputFormSubmittedError

Name	Type	Description	Required
HumanInputFormSubmittedError

HumanInputInvalidOtpError

Name	Type	Description	Required
HumanInputInvalidOtpError

HumanInputUploadTokenResponse

Name	Type	Description	Required
expires_at	integer		Yes
upload_token	string		Yes

HumanInputV2FormSubmitRequest

Public Human Input v2 submit payload, independent from the v1 form contract.

Name	Type	Description	Required
action	string	Identifier of the selected Human Input v2 action.	Yes
challenge_token	string	OTP challenge token returned by the Human Input v2 access-request endpoint.	No
inputs	object	Submitted form values keyed by output variable name.	Yes
otp_code	string	OTP code required when the current Human Input v2 approver uses email proof.	No

HumanInputV2RemoteUploadPayload

Name	Type	Description	Required
url	string (uri)		Yes

HumanInputV2UnavailableError

Name	Type	Description	Required
HumanInputV2UnavailableError

InvalidEmailError

The email address is not valid.

Name	Type	Description	Required
InvalidEmailError		The email address is not valid.

InvalidFormDataError

Name	Type	Description	Required
InvalidFormDataError

InvalidInputError

Name	Type	Description	Required
InvalidInputError

InvalidOrExpiredTokenError

The token is invalid or has expired.

Name	Type	Description	Required
InvalidOrExpiredTokenError		The token is invalid or has expired.

InvalidParamError

Name	Type	Description	Required
InvalidParamError

InvalidUploadTokenError

Upload token is invalid or expired.

Name	Type	Description	Required
InvalidUploadTokenError		Upload token is invalid or expired.

JSONValueType

Name	Type	Description	Required
JSONValueType

JsonValue

Name	Type	Description	Required
JsonValue

KnowledgeFsCitation

Immutable evidence identity; no signed URLs, tokens or storage keys.

Name	Type	Description	Required
artifact_hash	string		Yes
control_space_id	string		Yes
document_asset_id	string		Yes
document_title	string		No
document_version	integer		No
end_offset	integer		No
id	string		Yes
node_id	string		Yes
page_number	integer		No
parse_artifact_id	string		No
section_path	[ string ]		No
space_name	string		Yes
start_offset	integer		No

LicenseStatus

Name	Type	Description	Required
LicenseStatus	string

LicenseStatusModel

Name	Type	Description	Required
status	LicenseStatus		Yes

LoginPayload

Name	Type	Description	Required
email	string		Yes
password	string		Yes

LoginStatusQuery

Name	Type	Description	Required
app_code	string	Web app code	No
user_id	string	End user session ID	No

LoginStatusResponse

Name	Type	Description	Required
app_logged_in	boolean		Yes
logged_in	boolean		Yes

MalformedUploadTokenError

The upload token is malformed.

Name	Type	Description	Required
MalformedUploadTokenError		The upload token is malformed.

MarkdownFragment

One source-ordered Markdown fragment in a resolved form.

Name	Type	Description	Required
text	string		Yes
type	string		No

MessageFeedbackPayload

Name	Type	Description	Required
content	string	Optional text feedback providing additional detail.	No
rating	string, Available values: "dislike", "like"	Feedback rating. Set to null to revoke previously submitted feedback.	No

MessageFeedbackRatingRequiredError

A rating is required when there is no existing feedback to remove.

Name	Type	Description	Required
MessageFeedbackRatingRequiredError		A rating is required when there is no existing feedback to remove.

MessageFile

Name	Type	Description	Required
belongs_to	string		No
filename	string		Yes
id	string (uuid)		Yes
mime_type	string		No
size	integer		No
transfer_method	string		Yes
type	string		Yes
upload_file_id	string		No
url	string		No

MessageListQuery

Name	Type	Description	Required
conversation_id	string	Conversation ID.	Yes
first_id	string	The ID of the first chat record on the current page. Omit this value to fetch the latest messages; for subsequent pages, use the first message ID from the current list to fetch older messages.	No
limit	integer, Default: 20	Number of chat history messages to return per request.	No

MessageMoreLikeThisQuery

Name	Type	Description	Required
response_mode	string, Available values: "blocking", "streaming"	Response mode Enum: "blocking", "streaming"	Yes

ModelCurrentlyNotSupportError

Dify Hosted OpenAI trial currently not support the GPT-4 model.

Name	Type	Description	Required
ModelCurrentlyNotSupportError		Dify Hosted OpenAI trial currently not support the GPT-4 model.

NoAudioUploadedError

Please upload your audio.

Name	Type	Description	Required
NoAudioUploadedError		Please upload your audio.

NoFileUploadedError

Please upload your file.

Name	Type	Description	Required
NoFileUploadedError		Please upload your file.

NotChatAppError

Please check if your app mode matches the right API route.

Name	Type	Description	Required
NotChatAppError		Please check if your app mode matches the right API route.

NotCompletionAppError

Please check if your Completion app mode matches the right API route.

Name	Type	Description	Required
NotCompletionAppError		Please check if your Completion app mode matches the right API route.

NotWorkflowAppError

Please check if your Workflow app mode matches the right API route.

Name	Type	Description	Required
NotWorkflowAppError		Please check if your Workflow app mode matches the right API route.

ParagraphInput

Resolved multiline text input.

Name	Type	Description	Required
default_value	string		Yes
output_variable_name	string		Yes
type	string		No

ParagraphInputConfig

Form input definition.

Name	Type	Description	Required
default	StringSource	Raw default-value configuration for the paragraph input. Runtime-resolved values are exposed in the surrounding resolved_default_values mapping.	No
output_variable_name	string		Yes
type	string		No

Parameters

Name	Type	Description	Required
annotation_reply	{ "enabled": boolean }		Yes
file_upload	{ "allowed_file_extensions": [ string ], "allowed_file_types": [ string, Available values: "audio", "custom", "document", "image", "video" ], "allowed_file_upload_methods": [ string, Available values: "local_file", "remote_url" ], "enabled": boolean, "image": { "detail": string, "enabled": boolean, "number_limits": integer, "transfer_methods": [ string ] }, "number_limits": integer }		Yes
more_like_this	{ "enabled": boolean }		Yes
opening_statement			No
retriever_resource	{ "enabled": boolean }		Yes
sensitive_word_avoidance	{ "enabled": boolean }		Yes
show_thoughts	{ "enabled": boolean }		No
speech_to_text	{ "enabled": boolean }		Yes
suggested_questions	[ string ]		Yes
suggested_questions_after_answer	{ "enabled": boolean }		Yes
system_parameters	SystemParameters	System-level parameter limits.	Yes
text_to_speech	{ "autoPlay": string, "enabled": boolean, "language": string, "voice": string }		Yes
user_input_form	[ object ]		Yes

PassportAccessTokenResponse

Name	Type	Description	Required
access_token	string		Yes

PassportQuery

Name	Type	Description	Required
user_id	string	End user session ID	No

PasswordMismatchError

The passwords do not match.

Name	Type	Description	Required
PasswordMismatchError		The passwords do not match.

PasswordResetRateLimitExceededError

Too many password reset emails have been sent. Please try again in {minutes} minutes.

Name	Type	Description	Required
PasswordResetRateLimitExceededError		Too many password reset emails have been sent. Please try again in {minutes} minutes.

PluginInstallationPermissionModel

Name	Type	Description	Required
plugin_installation_scope	PluginInstallationScope		Yes
restrict_to_marketplace_only	boolean		Yes

PluginInstallationScope

Name	Type	Description	Required
PluginInstallationScope	string

ProviderNotInitializeError

No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.

Name	Type	Description	Required
ProviderNotInitializeError		No valid model provider credentials found. Please go to Settings -> Model Provider to complete your provider credentials.

ProviderNotSupportSpeechToTextError

Provider not support speech to text.

Name	Type	Description	Required
ProviderNotSupportSpeechToTextError		Provider not support speech to text.

ProviderQuotaExceededError

Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.

Name	Type	Description	Required
ProviderQuotaExceededError		Your quota for Dify Hosted OpenAI has been exhausted. Please go to Settings -> Model Provider to complete your own provider credentials.

RateLimitError

Rate Limit Error

Name	Type	Description	Required
RateLimitError		Rate Limit Error

RemoteFileAccessDeniedError

The remote file cannot be accessed without authorization.

Name	Type	Description	Required
RemoteFileAccessDeniedError		The remote file cannot be accessed without authorization.

RemoteFileInfo

Name	Type	Description	Required
file_length	integer		Yes
file_type	string		Yes

RemoteFileInvalidResponseError

The remote file server returned an invalid response.

Name	Type	Description	Required
RemoteFileInvalidResponseError		The remote file server returned an invalid response.

RemoteFileInvalidUrlError

The remote file URL is invalid.

Name	Type	Description	Required
RemoteFileInvalidUrlError		The remote file URL is invalid.

RemoteFileNotFoundError

The remote file could not be found.

Name	Type	Description	Required
RemoteFileNotFoundError		The remote file could not be found.

RemoteFileUnavailableError

The remote file is temporarily unavailable.

Name	Type	Description	Required
RemoteFileUnavailableError		The remote file is temporarily unavailable.

RemoteFileUploadPayload

Name	Type	Description	Required
url	string (uri)	Remote file URL	Yes

RemoteFileUrlBlockedError

The remote file URL is not allowed.

Name	Type	Description	Required
RemoteFileUrlBlockedError		The remote file URL is not allowed.

ResolvedForm

Immutable authoritative presentation snapshot for one v2 form.

Name	Type	Description	Required
actions	[ UserAction ]		Yes
legacy_form_content	string		Yes
parts	[ FormPart ]		Yes
title	string		Yes

ResultResponse

Name	Type	Description	Required
result	string		Yes

RetrieverResource

Name	Type	Description	Required
content	string		No
created_at	integer		No
data_source_type	string		No
dataset_id	string		No
dataset_name	string		No
doc_metadata	object		No
document_asset_id	string		No
document_id	string		No
document_name	string		No
document_revision	integer		No
document_version	integer		No
files	[ object ]		No
hit_count	integer		No
id	string (uuid)		No
index_node_hash	string		No
knowledge_fs_citation	KnowledgeFsCitation		No
message_id	string (uuid)		No
page	integer		No
position	integer		Yes
retriever_from	string		No
score	number		No
segment_id	string		No
segment_position	integer		No
summary	string		No
title	string		No
word_count	integer		No

SSOProtocol

Name	Type	Description	Required
SSOProtocol	string

SavedMessageCreatePayload

Name	Type	Description	Required
message_id	string		Yes

SavedMessageInfiniteScrollPagination

Name	Type	Description	Required
data	[ SavedMessageItem ]		Yes
has_more	boolean		Yes
limit	integer		Yes

SavedMessageItem

Name	Type	Description	Required
answer	string		Yes
created_at	integer		No
feedback	SimpleFeedback		No
id	string		Yes
inputs	object		Yes
message_files	[ MessageFile ]		Yes
query	string		Yes

SavedMessageListQuery

Name	Type	Description	Required
last_id	string		No
limit	integer, Default: 20		No

SelectInput

Resolved single-choice input with immutable concrete options.

Name	Type	Description	Required
default_value	string		Yes
options	[ string ]		Yes
output_variable_name	string		Yes
type	string		No

SelectInputConfig

Name	Type	Description	Required
option_source	StringListSource	Source of options for select inputs. Present only when type is select.	Yes
output_variable_name	string		Yes
type	string		No

ShallowJSONValue

Name	Type	Description	Required
ShallowJSONValue	string integer number boolean object [ object ]

SimpleConversation

Name	Type	Description	Required
created_at	integer		No
id	string (uuid)		Yes
inputs	object		Yes
introduction	string		No
name	string		Yes
status	string		Yes
updated_at	integer		No

SimpleFeedback

Name	Type	Description	Required
rating	string		No

SimpleResultDataResponse

Name	Type	Description	Required
data	string		Yes
result	string		Yes

SimpleResultResponse

Name	Type	Description	Required
result	string	Operation result.	Yes

SpeechToTextDisabledError

Speech to text is disabled.

Name	Type	Description	Required
SpeechToTextDisabledError		Speech to text is disabled.

StringListSource

Name	Type	Description	Required
selector	[ string ]	Variable reference path when type is variable.	No
type	ValueSourceType	Origin of the options. constant means value lists the options literally; variable means selector points to an array[string] workflow variable that provides them.	Yes
value	[ string ]	Literal option list when type is constant.	No

StringSource

Default configuration for form inputs.

Name	Type	Description	Required
selector	[ string ]		No
type	ValueSourceType		Yes
value	string		No

SuggestedQuestionsResponse

Name	Type	Description	Required
data	[ string ]		Yes

SystemFeatureModel

Non-sensitive bootstrap snapshot exposed before Console or Web authentication.

Name	Type	Description	Required
agent_tracing_api_collection_enabled	boolean	Deployment-level API gate for Agent trace collection, independent of workspace and provider configuration. Does not indicate Agent runtime, worker, or provider health or confirm trace delivery.	Yes
branding	BrandingModel		Yes
deployment_edition	DeploymentEdition		Yes
enable_app_deploy	boolean		Yes
enable_change_email	boolean, Default: true		Yes
enable_collaboration_mode	boolean, Default: true		Yes
enable_creators_platform	boolean		Yes
enable_email_code_login	boolean		Yes
enable_email_password_login	boolean, Default: true		Yes
enable_explore_banner	boolean		Yes
enable_learn_app	boolean, Default: true		Yes
enable_marketplace	boolean		Yes
enable_social_oauth_login	boolean		Yes
enable_step_by_step_tour	boolean		Yes
is_allow_register	boolean		Yes
is_email_setup	boolean		Yes
license	LicenseStatusModel		Yes
plugin_installation_permission	PluginInstallationPermissionModel		Yes
rbac_enabled	boolean		Yes
sso_enforced_for_signin	boolean		Yes
sso_enforced_for_signin_protocol	SSOProtocol		Yes
webapp_auth	WebAppAuthModel		Yes

SystemParameters

Name	Type	Description	Required
audio_file_size_limit	integer		Yes
file_size_limit	integer		Yes
image_file_size_limit	integer		Yes
video_file_size_limit	integer		Yes
workflow_file_upload_limit	integer		Yes

TextToAudioPayload

Name	Type	Description	Required
message_id	string	Message ID. Takes priority over text when both are provided.	No
streaming	boolean	Reserved for compatibility; TTS response streaming is determined by the provider output.	No
text	string	Speech content to convert.	No
voice	string	Voice to use for text-to-speech. Available voices depend on the TTS provider configured for this app. Omit to use the app's configured voice when available; that value is exposed by Get App Parameters as text_to_speech.voice.	No

TooManyFilesError

Only one file is allowed.

Name	Type	Description	Required
TooManyFilesError		Only one file is allowed.

TriggerWorkflowServiceModeUnavailableError

This workflow uses a trigger entry and cannot be invoked through Web App, Service API, OpenAPI, or MCP.

Name	Type	Description	Required
TriggerWorkflowServiceModeUnavailableError		This workflow uses a trigger entry and cannot be invoked through Web App, Service API, OpenAPI, or MCP.

UnsupportedAudioTypeError

Audio type not allowed.

Name	Type	Description	Required
UnsupportedAudioTypeError		Audio type not allowed.

UnsupportedFileTypeError

File type not allowed.

Name	Type	Description	Required
UnsupportedFileTypeError		File type not allowed.

UploadTokenRequiredError

Upload token is required.

Name	Type	Description	Required
UploadTokenRequiredError		Upload token is required.

UserAction

Resolved action values required for presentation and submission validation.

Name	Type	Description	Required
button_style	ButtonStyle		Yes
id	string		Yes
title	string		Yes

UserActionConfig

User action configuration.

Name	Type	Description	Required
button_style	ButtonStyle		No
id	string		Yes
title	string		Yes

ValueSourceType

ValueSourceType records whether the value comes from a static setting in form definition, or a variable while the workflow is running.

Name	Type	Description	Required
ValueSourceType	string	ValueSourceType records whether the value comes from a static setting in form definition, or a variable while the workflow is running.

VerificationTokenResponse

Name	Type	Description	Required
email	string		Yes
is_valid	boolean		Yes
token	string		Yes

WebAppAuthModel

Name	Type	Description	Required
allow_email_code_login	boolean		Yes
allow_email_password_login	boolean		Yes
allow_public_access	boolean, Default: true		Yes
allow_sso	boolean		Yes
enabled	boolean		Yes
sso_config	WebAppAuthSSOModel		Yes

WebAppAuthSSOModel

Name	Type	Description	Required
protocol	SSOProtocol		Yes

WebAppCustomConfigResponse

Name	Type	Description	Required
remove_webapp_brand	boolean		Yes
replace_webapp_logo	string		No

WebAppHumanInputV2FormDefinitionResponse

Name	Type	Description	Required
expiration_time	integer		Yes
resolved_form	ResolvedForm		Yes

WebAppHumanInputV2SubmitPayload

Name	Type	Description	Required
action	string		Yes
inputs	object		Yes

WebAppHumanInputV2SubmitResponse

Name	Type	Description	Required

WebAppSiteResponse

Name	Type	Description	Required
app_id	string		Yes
can_replace_logo	boolean		Yes
custom_config	WebAppCustomConfigResponse		No
enable_site	boolean		Yes
end_user_id	string		No
mode	AppMode		Yes
model_config	WebModelConfigResponse		No
plan	string		Yes
site	WebSiteResponse		Yes

WebFormRateLimitExceededError

Too many form requests. Please try again later.

Name	Type	Description	Required
WebFormRateLimitExceededError		Too many form requests. Please try again later.

WebMessageInfiniteScrollPagination

Name	Type	Description	Required
data	[ WebMessageListItem ]		Yes
has_more	boolean		Yes
limit	integer		Yes

WebMessageListItem

Name	Type	Description	Required
agent_thoughts	[ AgentThought ]		Yes
answer	string		Yes
answer_tokens	integer		No
conversation_id	string (uuid)		Yes
created_at	integer		No
currency	string		No
error	string		No
extra_contents	[ HumanInputContent ]		Yes
feedback	SimpleFeedback		No
id	string (uuid)		Yes
inputs	object		Yes
message_files	[ MessageFile ]		Yes
message_tokens	integer		No
metadata	JSONValueType		No
parent_message_id	string		No
provider_response_latency	float		No
query	string		Yes
retriever_resources	[ RetrieverResource ]		Yes
status	string		Yes
total_price	string		No
total_tokens	integer		Yes

WebModelConfigResponse

Name	Type	Description	Required
model			No
more_like_this			No
opening_statement	string		No
pre_prompt	string		No
suggested_questions			No
suggested_questions_after_answer			No
user_input_form			No

WebSiteResponse

Name	Type	Description	Required
chat_color_theme	string		No
chat_color_theme_inverted	boolean		Yes
copyright	string		No
custom_disclaimer	string		No
default_language	string		No
description	string		No
icon	string		No
icon_background	string		No
icon_type	string		No
icon_url	string		No
input_placeholder	string		No
privacy_policy	string		No
prompt_public	boolean		No
show_workflow_steps	boolean		No
title	string		Yes
use_icon_as_answer_icon	boolean		No

WorkflowNotActiveError

Name	Type	Description	Required
WorkflowNotActiveError

WorkflowRunPayload

Name	Type	Description	Required
files	[ object object object object ]	File list for workflow system file inputs. Available when file upload is enabled for the workflow. To attach a local file, first upload it via Upload File and use the returned id as upload_file_id with transfer_method: local_file.	No
inputs	object	Key-value pairs for workflow input variables. Values for file-type variables should be arrays of file objects with type, transfer_method, and either url or upload_file_id. Refer to the user_input_form field in the Get App Parameters response to discover the variable names and types expected by your app.	Yes