Skip to main content
POST
cURL

Authorizations

Authorization
string
header
required

Every request authenticates with an API key: Authorization: Bearer {API_KEY}. App endpoints take an app API key; knowledge endpoints take a knowledge base API key (Get Started).

Keep keys server-side; never embed them in client code. Requests with a missing or invalid key fail with HTTP 401 (unauthorized).

Body

application/json

Request body to send a chat message.

query
string
required

The user's message.

inputs
object
required

Values for the app's input variables, keyed by variable name. The expected names and types come from the user_input_form field of Get App Parameters.

user
string
required

End-user identifier, defined by your app and unique within it. Conversations, messages, and files are visible only to requests carrying the same user. See End User Identity.

response_mode
enum<string>

Mode of response return. Defaults to blocking when omitted.

  • streaming (recommended): the reply arrives as Server-Sent Events.
  • blocking: returns once generation completes. Long generations risk interruption: a reverse proxy in front of the API may end the connection if the response doesn't arrive within its timeout.
  • Agent apps support streaming only; a blocking request fails with 400.
Available options:
streaming,
blocking
conversation_id
string

ID of the conversation to continue. Omit it or pass an empty string to start a new conversation; the response returns a conversation_id to send with the next message. To resume an earlier conversation, get its ID from List Conversations.

files
object[]

Files to attach to the message. For a local file, first upload it via Upload File, then reference the returned id as upload_file_id with transfer_method: local_file.

auto_generate_name
boolean
default:true

Auto-generate conversation title. If false, use the Rename Conversation API with auto_generate: true for async title generation.

workflow_id
string

Chatflow apps only. Specify a published workflow version ID to execute. If not provided, the latest published version is used. Available since Dify Enterprise 3.4.1.

Response

Successful response. The content type and structure depend on the response_mode parameter in the request.

  • If response_mode is blocking, returns application/json with a ChatCompletionResponse object.
  • If response_mode is streaming, returns text/event-stream with a stream of Server-Sent Events.
event
string

Event type, fixed as message.

task_id
string<uuid>

Task ID for request tracking and stop response API.

id
string<uuid>

Unique ID of this response event.

message_id
string<uuid>

Unique message ID. Use this as the message_id parameter when calling feedback or suggested questions endpoints.

conversation_id
string<uuid>

Conversation ID.

mode
string

App mode. chat for Chatbot apps, agent-chat for Agent apps, advanced-chat for Chatflow apps.

answer
string

Complete response content.

metadata
object

Metadata including usage and retriever resources.

created_at
integer<int64>

Message creation timestamp (Unix epoch seconds).