Dify API Guide 2026: Integrate AI into Your App with REST

What is the Dify API?

The Dify API is a REST API that lets you programmatically call any app you build in Dify — from any programming language or platform. Once you publish a Dify app (chatbot, agent, workflow, or completion app), it gets its own API endpoint you can call with a secret key.

The base URL for Dify Cloud is https://api.dify.ai/v1. If you self-host Dify, replace this with your own domain: https://your-server.com/v1.

Common use cases

API Endpoints Overview

The Dify API provides endpoints for sending messages, managing conversations, uploading files, and more. All endpoints are relative to the base URL https://api.dify.ai/v1.

Streaming Responses (SSE)

Streaming lets you display tokens as they're generated — like ChatGPT's typing effect. Dify uses Server-Sent Events (SSE) for streaming. Set "response_mode": "streaming" in your request body.

Each event arrives as a line prefixed with data:. The event types include message (a token chunk), message_end (final message with metadata), and error.

Streaming curl example

curl -X POST 'https://api.dify.ai/v1/chat-messages' \
  -H 'Authorization: Bearer YOUR_API_KEY' \
  -H 'Content-Type: application/json' \
  --no-buffer \
  -d '{
    "inputs": {},
    "query": "Write a short poem about AI.",
    "response_mode": "streaming",
    "conversation_id": "",
    "user": "user-123"
  }'

# Output (one line per token chunk):
# data: {"event":"message","answer":"In",...}
# data: {"event":"message","answer":" circuits",...}
# data: {"event":"message","answer":" deep",...}
# data: {"event":"message_end","metadata":{"usage":{...}}}}

Python streaming example

import requests
import json

def stream_chat(query, user="user-123"):
    with requests.post(
        "https://api.dify.ai/v1/chat-messages",
        headers={
            "Authorization": "Bearer YOUR_API_KEY",
            "Content-Type": "application/json",
        },
        json={
            "inputs": {},
            "query": query,
            "response_mode": "streaming",
            "conversation_id": "",
            "user": user,
        },
        stream=True,
    ) as response:
        for line in response.iter_lines():
            if line and line.startswith(b"data: "):
                data = json.loads(line[6:])
                if data.get("event") == "message":
                    print(data["answer"], end="", flush=True)
                elif data.get("event") == "message_end":
                    print()  # newline at end
                    break

stream_chat("Explain quantum computing in simple terms.")

JavaScript / Browser (EventSource)

// Note: EventSource doesn't support POST with a body.
// Use fetch with ReadableStream instead for browser streaming.

async function streamChat(query) {
  const response = await fetch("https://api.dify.ai/v1/chat-messages", {
    method: "POST",
    headers: {
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      inputs: {},
      query,
      response_mode: "streaming",
      conversation_id: "",
      user: "user-browser",
    }),
  });

  const reader = response.body.getReader();
  const decoder = new TextDecoder();

  while (true) {
    const { done, value } = await reader.read();
    if (done) break;
    const lines = decoder.decode(value).split("\n");
    for (const line of lines) {
      if (line.startsWith("data: ")) {
        const data = JSON.parse(line.slice(6));
        if (data.event === "message") {
          document.getElementById("output").textContent += data.answer;
        }
      }
    }
  }
}

streamChat("What are the benefits of self-hosting AI?");

Frequently Asked Questions