Dify Reference SKILL
Find syntax, API, CLI, and other reference information
Quick Navigation
DSL Syntax Reference
Workflow DSL Structure
version: 0.0.1
graph:
nodes:
- id: node_id
data:
type: node_type
# node configuration
edges:
- source: source_node_id
target: target_node_id
Node Types
| Type | Description | Required Fields |
|---|---|---|
start | Start node | variables |
llm | LLM node | model, prompt_template |
agent | Agent node | agent_parameters |
knowledge-retrieval | Knowledge retrieval | dataset_ids, query_variable_selector |
http-request | HTTP request | url, method, headers |
code | Code execution | code_type, code |
tool | Tool node | provider_type, tool_name |
if-else | Conditional branch | conditions |
iteration | Iteration | iterator_variable_name |
loop | Loop | max_loop_count |
answer | Response node | answer |
Variable References
# System variables
{{#sys.query#}} # User query
{{#sys.files#}} # Uploaded files
{{#sys.conversation_id#}} # Conversation ID
# Node outputs
{{#node_id.output_field#}}
# Array access
{{#items[0]#}} # First element of array
{{#items[-1]#}} # Last element of array
# Object properties
{{#object.field#}} # Object property
Complete Example
workflow:
graph:
nodes:
- id: start
data:
type: start
variables:
- name: query
type: text
required: true
- id: classify
data:
type: question-classifier
instruction: "Classify the user question"
categories:
- name: technical
description: Technical problem
- name: general
description: General question
- id: llm
data:
type: llm
model:
provider: openai
name: gpt-4
prompt_template:
- role: system
text: "You are an assistant"
- role: user
text: "{{#start.query#}}"
context:
enabled: false
- id: answer
data:
type: answer
answer: "{{#llm.text#}}"
edges:
- source: start
target: classify
- source: classify
target: llm
source_handle: general
- source: llm
target: answer
API Reference
Authentication
All API requests require an API Key in the Header:
Authorization: Bearer YOUR_API_KEY
Endpoint Overview
Application API
| Endpoint | Method | Description |
|---|---|---|
/v1/chat-messages | POST | Send a chat message |
/v1/completions | POST | Text completion |
/v1/parameters | GET | Get application parameters |
/v1/file-upload | POST | File upload |
Workflow API
| Endpoint | Method | Description |
|---|---|---|
/v1/workflows/run | POST | Run a workflow |
/v1/workflows/run | GET | Get run status |
/v1/workflows/tasks | GET | List tasks |
Dataset API
| Endpoint | Method | Description |
|---|---|---|
/v1/datasets | GET | List datasets |
/v1/datasets | POST | Create a dataset |
/v1/datasets/{id}/documents | GET | List documents |
/v1/datasets/{id}/retrieve | POST | Retrieve knowledge |
Request/Response Format
Chat Message Request
{
"query": "User query",
"user": "user_123",
"conversation_id": "optional conversation ID",
"response_mode": "blocking | streaming",
"files": [
{
"type": "image",
"transfer_method": "remote_url",
"url": "https://example.com/image.jpg"
}
],
"retrieval_model": {
"query": "{{#sys.query#}}",
"top_k": 3
}
}
Chat Message Response
{
"message_id": "msg_xxx",
"conversation_id": "conv_xxx",
"answer": "AI response content",
"metadata": {
"usage": {
"prompt_tokens": 100,
"completion_tokens": 50,
"total_tokens": 150
},
"retrieval_resources": [
{
"position": 1,
"document_id": "doc_xxx",
"content": "Relevant document content..."
}
]
}
}
Error Responses
{
"code": "invalid_api_key",
"message": "Invalid API key",
"status_code": 401
}
Common Error Codes:
| Error Code | HTTP Status Code | Description |
|---|---|---|
invalid_api_key | 401 | Invalid API Key |
invalid_parameter | 400 | Invalid parameter |
quota_exceeded | 403 | Quota exceeded |
rate_limit_exceeded | 429 | Rate limit exceeded |
internal_server_error | 500 | Internal server error |
SDK Reference
Python SDK
Installation
pip install dify-client
Basic Usage
from dify_client import DifyClient
# Initialize client
client = DifyClient(
api_key="app-xxx",
base_url="https://api.dify.ai/v1"
)
# Send a chat message
response = client.chat.messages.create(
query="Hello",
user="user_123"
)
print(response.answer)
Streaming Response
from dify_client import DifyClient
client = DifyClient(api_key="app-xxx")
# Streaming chat
for event in client.chat.messages.stream(
query="Tell me a story",
user="user_123"
):
if event.event == "message":
print(event.data.answer, end="")
Workflow Execution
# Run a workflow
response = client.workflows.run(
inputs={"query": "test"},
user="user_123",
response_mode="blocking"
)
print(response.data.output)
SDK Class Reference
DifyClient
class DifyClient:
def __init__(self, api_key: str, base_url: str = "https://api.dify.ai/v1"):
"""Initialize the client"""
pass
@property
def chat(self) -> ChatClient:
"""Chat client"""
pass
@property
def workflows(self) -> WorkflowClient:
"""Workflow client"""
pass
@property
def datasets(self) -> DatasetClient:
"""Dataset client"""
pass
ChatClient
class ChatClient:
def create(self, query: str, user: str, **kwargs) -> ChatMessage:
"""Send a chat message (blocking)"""
pass
def stream(self, query: str, user: str, **kwargs) -> Iterator[ChatEvent]:
"""Send a chat message (streaming)"""
pass
CLI Reference
Installation
pip install dify-cli
Command Overview
Plugin Commands
# Initialize a plugin
dify plugin init [options]
# Run a plugin
dify plugin run [options]
# Package a plugin
dify plugin package [options]
# Publish a plugin
dify plugin publish [options]
# List installed plugins
dify plugin list
Workflow Commands
# Export a workflow
dify workflow export <workflow_id> [options]
# Import a workflow
dify workflow import <file> [options]
# Validate a workflow
dify workflow validate <file>
# Run a workflow
dify workflow run <workflow_id> --inputs '{}'
Application Commands
# List applications
dify app list
# Get application info
dify app info <app_id>
# Deploy an application
dify app deploy <app_id>
Environment Variable Commands
# List environment variables
dify env list
# Set an environment variable
dify env set <key> <value>
# Get an environment variable
dify env get <key>
# Delete an environment variable
dify env delete <key>
Option Reference
| Option | Short | Description | Default |
|---|---|---|---|
--api-key | -k | API Key | Environment variable DIFY_API_KEY |
--base-url | -b | Base URL | https://api.dify.ai/v1 |
--output | -o | Output format | json |
--quiet | -q | Quiet mode | false |
--debug | -d | Debug mode | false |
Usage Examples
# Set API Key
export DIFY_API_KEY="app-xxx"
# Initialize a plugin project
dify plugin init my-plugin --template tool
# Run a plugin
dify plugin run --port 5000
# Export a workflow
dify workflow export wf_xxx -o workflow.yaml
# Import a workflow
dify workflow import workflow.yaml
Frequently Asked Questions
API Related
Q: How do I get an API Key? A: Create one in Dify Console -> Settings -> API.
Q: What is the request rate limit? A: Default is 60 requests/minute, can be increased upon request.
Q: How do I handle streaming responses?
A: Use response_mode=streaming and parse SSE events.
Workflow Related
Q: How do I reference variables?
A: Use the {{#node_id.field#}} syntax.
Q: Which node types are supported? A: See the Node Types table for details.
Q: How do I handle loops?
A: Use iteration or loop nodes.
Plugin Related
Q: How do I develop custom plugins? A: Refer to the 02-plugin SKILL.
Q: How does a plugin obtain credentials?
A: Use self.runtime_credentials.
Related SKILLs
- 01-workflow - Workflow Design
- 02-plugin - Plugin Development
- 05-integration - Integration Extensions
Related Resources
Version: v1.0.0 | Last Updated: 2026-03-05