This page details the official client SDKs provided by Dify for integrating with its APIs. It covers the Node.js SDK, the community-contributed PHP client, their API coverage, and provides usage examples for common Dify functionalities. These SDKs simplify interaction with Dify's chat, completion, workflow, and knowledge base APIs, abstracting away direct HTTP requests and handling authentication.
The Dify Node.js SDK, named dify-client, provides a convenient way to interact with the Dify API from Node.js applications. The project is managed using pnpm and is located in the sdks/nodejs-client directory <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/pnpm-workspace.yaml#L26-L26" min=26 file-path="pnpm-workspace.yaml">Hii</FileRef>.
The Node.js SDK is published as a package and can be installed via npm or pnpm:
Sources: <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/sdks/nodejs-client/package.json#L1-L10" min=1 max=10 file-path="sdks/nodejs-client/package.json">Hii</FileRef>
The Node.js SDK is structured into several client classes, each responsible for a specific set of Dify API functionalities. These clients share a common underlying HTTP client for making requests.
DifyClient: Provides general application-level APIs such as fetching application parameters, message feedback, file uploads, and audio/text conversions.ChatClient: Handles chat-specific operations, including creating chat messages (blocking and streaming), stopping messages, retrieving suggested questions, managing conversations, and handling annotations.CompletionClient: Manages completion-specific interactions, such as creating completion messages (blocking and streaming) and stopping completion tasks.WorkflowClient: Facilitates running Dify workflows.KnowledgeBaseClient: Provides methods for managing datasets, documents, segments, child chunks, metadata, and running RAG pipelines.WorkspaceClient: Used for workspace-level operations, such as retrieving models by type.These classes encapsulate specific API route functionalities and provide typed interfaces for interacting with the backend.
The SDK supports both blocking and streaming response modes. For streaming responses, the SDK implements logic to process Server-Sent Events (SSE) using an event-source parser. This enables real-time streamed updates from the server, yielding individual chunks of data as they arrive.
Data Flow for Streaming Responses:
This pattern is consistent across chat, completion, and workflow streaming APIs, allowing client applications to process partial results as they are generated.
Sources:
<FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/sdks/nodejs-client/package.json#L1-L10" min=1 max=10 file-path="sdks/nodejs-client/package.json">Hii</FileRef><FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_chat.en.mdx?plain=1#L46-L51" min=46 max=51 file-path="web/app/components/develop/template/template_chat.en.mdx">Hii</FileRef><FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_workflow.en.mdx?plain=1#L54-L58" min=54 max=58 file-path="web/app/components/develop/template/template_workflow.en.mdx">Hii</FileRef>The following is an example of using the Node.js SDK to interact with the Dify API for chat and workflow operations.
This example demonstrates typical usage of streaming chat messages and running workflows synchronously.
Sources: <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_chat.en.mdx?plain=1#L24-L92" min=24 max=92 file-path="web/app/components/develop/template/template_chat.en.mdx">Hii</FileRef>
<FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_workflow.en.mdx?plain=1#L25-L75" min=25 max=75 file-path="web/app/components/develop/template/template_workflow.en.mdx">Hii</FileRef>
The Node.js SDK is published from the Dify repository workspace via a shell script publish.sh located in the sdks/nodejs-client/scripts/ directory. The script performs git status checks, version validations, testing, build, and finally publishes the package to npm.
Sources: <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/sdks/nodejs-client/scripts/publish.sh#L1-L20" min=1 max=20 file-path="sdks/nodejs-client/scripts/publish.sh">Hii</FileRef>
The Dify PHP SDK is a community-contributed client for integrating Dify into PHP applications. It uses the Guzzle HTTP client to perform API requests.
The PHP client includes a base DifyClient class and specialized classes extending it: CompletionClient, ChatClient, and WorkflowClient.
DifyClient: Manages API base URL configuration, handles the Authorization header (Bearer {API_KEY}) for authentication, and sends HTTP requests to the Dify API.CompletionClient: Extends DifyClient and provides methods to create completion messages with the API.ChatClient: Extends DifyClient and handles chat message creation, suggested question retrieval, and conversation CRUD operations.WorkflowClient: Extends DifyClient and supports running workflows and stopping workflow executions.This client abstracts the API endpoints and simplifies usage for PHP developers by encapsulating request building and response parsing.
Sources: <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/sdks/php-client/dify-client.php#L5-L150" min=5 max=150 file-path="sdks/php-client/dify-client.php">Hii</FileRef>
The following diagram bridges the Natural Language Space (SDK function calls) to the Code Entity Space (API Endpoints). It illustrates which SDK client methods correspond to which backend API endpoints.
This mapping clarifies how SDK usage translates to actual REST API calls in the backend.
Sources:
<FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_chat.en.mdx?plain=1#L24-L29" min=24 max=29 file-path="web/app/components/develop/template/template_chat.en.mdx">Hii</FileRef><FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_workflow.en.mdx?plain=1#L25-L29" min=25 max=29 file-path="web/app/components/develop/template/template_workflow.en.mdx">Hii</FileRef><FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_advanced_chat.en.mdx?plain=1#L24-L29" min=24 max=29 file-path="web/app/components/develop/template/template_advanced_chat.en.mdx">Hii</FileRef>Dify APIs utilize SSE (Server-Sent Events) to provide real-time streaming feedback. The SDKs parse these events for the end-user. The following table summarizes key event types emitted during streaming responses.
| Event Type | Description | Reference |
|---|---|---|
message | LLM returns a text chunk | <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_chat.en.mdx?plain=1#L121-L121" min=121 file-path="web/app/components/develop/template/template_chat.en.mdx">Hii</FileRef> |
agent_thought | Agent thinking or tool use | <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_chat.zh.mdx?plain=1#L133-L133" min=133 file-path="web/app/components/develop/template/template_chat.zh.mdx">Hii</FileRef> |
workflow_started | Workflow execution started | <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_workflow.en.mdx?plain=1#L105-L105" min=105 file-path="web/app/components/develop/template/template_workflow.en.mdx">Hii</FileRef> |
node_started | Specific workflow node started | <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_workflow.en.mdx?plain=1#L113-L113" min=113 file-path="web/app/components/develop/template/template_workflow.en.mdx">Hii</FileRef> |
text_chunk | Text output from workflow node | <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_workflow.en.mdx?plain=1#L126-L126" min=126 file-path="web/app/components/develop/template/template_workflow.en.mdx">Hii</FileRef> |
message_end | Stream completion notification | <FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_chat.en.mdx?plain=1#L142-L142" min=142 file-path="web/app/components/develop/template/template_chat.en.mdx">Hii</FileRef> |
These events are important for clients wishing to process partial results or update UI state during streaming API responses.
Sources:
<FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_chat.en.mdx?plain=1#L112-L160" min=112 max=160 file-path="web/app/components/develop/template/template_chat.en.mdx">Hii</FileRef><FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_workflow.en.mdx?plain=1#L96-L165" min=96 max=165 file-path="web/app/components/develop/template/template_workflow.en.mdx">Hii</FileRef>Dify provides official client SDKs primarily for Node.js, covering comprehensive API functionalities including chat, completion, workflows, and knowledge base management. A community-supported PHP client is available for PHP developers. These SDKs abstract the raw HTTP API, handle authentication and streaming protocols, and provide idiomatic usage patterns to ease integration.
The key SDKs include:
| SDK | Supported Language | Coverage | Key Features |
|---|---|---|---|
dify-client | Node.js | Chat, Completion, Workflow, KnowledgeBase, File Uploads | SSE streaming handling, typed client interfaces |
| PHP Client | PHP | Chat, Completion, Workflow | Guzzle-based HTTP client, simple request wrappers |
Integrating with these SDKs enables rapid development of Dify-powered applications without managing low-level HTTP details.
Sources:
<FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/sdks/nodejs-client/package.json" undefined file-path="sdks/nodejs-client/package.json">Hii</FileRef><FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/sdks/nodejs-client/scripts/publish.sh" undefined file-path="sdks/nodejs-client/scripts/publish.sh">Hii</FileRef><FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/sdks/php-client/dify-client.php" undefined file-path="sdks/php-client/dify-client.php">Hii</FileRef><FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_chat.en.mdx?plain=1" undefined file-path="web/app/components/develop/template/template_chat.en.mdx">Hii</FileRef><FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_workflow.en.mdx?plain=1" undefined file-path="web/app/components/develop/template/template_workflow.en.mdx">Hii</FileRef><FileRef file-url="https://github.com/langgenius/dify/blob/8946d7fb/web/app/components/develop/template/template_advanced_chat.en.mdx?plain=1" undefined file-path="web/app/components/develop/template/template_advanced_chat.en.mdx">Hii</FileRef>Refresh this wiki
This wiki was recently refreshed. Please wait 6 days to refresh again.