Chat Completion

Dify — Chat & Completion Messages

Sending messages to Dify apps and managing the message lifecycle. For auth, base URL, the user field, and response modes, see the setup skill. For SSE event details see references/streaming-events.md.

POST /chat-messages — chat / agent / chatflow apps

Stateful conversation. Omit conversation_id (or send "") to start a new conversation; pass the returned conversation_id to continue it.

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  --header 'Authorization: Bearer app-XXXX' \
  --header 'Content-Type: application/json' \
  --data '{
    "query": "What is Dify?",
    "inputs": {},
    "response_mode": "streaming",
    "user": "user-123",
    "conversation_id": ""
  }'

Blocking response (shape):

{
  "event": "message",
  "task_id": "...",
  "message_id": "...",
  "conversation_id": "...",
  "mode": "chat",
  "answer": "Dify is an LLM app development platform...",
  "metadata": { "usage": { "total_tokens": 42 }, "retriever_resources": [] },
  "created_at": 1700000000
}

In streaming mode the answer arrives across message events and ends with message_end (carrying conversation_id, message_id, and metadata.usage). See the references file.

POST /completion-messages — text generation (completion) apps

Stateless, single-shot. No conversation_id. The prompt comes from inputs (the app's defined variables); query is usually "".

curl -X POST 'https://api.dify.ai/v1/completion-messages' \
  --header 'Authorization: Bearer app-XXXX' \
  --header 'Content-Type: application/json' \
  --data '{
    "inputs": { "topic": "renewable energy" },
    "response_mode": "blocking",
    "user": "user-123"
  }'

Returns the same message/message_end shape with "mode": "completion".

Stop generation (streaming only)

Use the task_id from any streamed event. The user must match the one that started it.

# Chat / chatflow
curl -X POST 'https://api.dify.ai/v1/chat-messages/{task_id}/stop' \
  --header 'Authorization: Bearer app-XXXX' \
  --header 'Content-Type: application/json' \
  --data '{ "user": "user-123" }'

# Completion
curl -X POST 'https://api.dify.ai/v1/completion-messages/{task_id}/stop' \
  --header 'Authorization: Bearer app-XXXX' \
  --header 'Content-Type: application/json' \
  --data '{ "user": "user-123" }'

Returns { "result": "success" }.

GET /messages/{message_id}/suggested — next questions

Returns AI-suggested follow-up questions for a message (if enabled on the app).

curl 'https://api.dify.ai/v1/messages/{message_id}/suggested?user=user-123' \
  --header 'Authorization: Bearer app-XXXX'

{ "result": "success", "data": ["How do I deploy it?", "Is it open source?"] }

POST /messages/{message_id}/feedback — like / dislike

curl -X POST 'https://api.dify.ai/v1/messages/{message_id}/feedback' \
  --header 'Authorization: Bearer app-XXXX' \
  --header 'Content-Type: application/json' \
  --data '{ "rating": "like", "content": "Helpful!", "user": "user-123" }'

rating is like, dislike, or null (to revoke). Returns { "result": "success" }.

GET /app/feedbacks — list app feedbacks

curl 'https://api.dify.ai/v1/app/feedbacks?page=1&limit=20' \
  --header 'Authorization: Bearer app-XXXX'

Returns { "data": [ { "id", "message_id", "rating", "content", "from_end_user_id", "created_at" } ] }.

Endpoint summary

Related: chat history & message listing → conversations skill · SSE events → references/streaming-events.md.