Agent Skills: dify

Troubleshooting

If requests fail, run zero doctor check-connector --env-name DIFY_TOKEN or zero doctor check-connector --url https://api.dify.ai/v1/chat-messages --method POST

Chat Messages

Send Chat Message (Blocking)

Write to /tmp/dify_request.json:

{
  "inputs": {},
  "query": "What is Dify?",
  "response_mode": "blocking",
  "user": "user-123"
}

Then run:

curl -s -X POST "https://api.dify.ai/v1/chat-messages" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d @/tmp/dify_request.json | jq .

Send Chat Message (Streaming)

Write to /tmp/dify_request.json:

{
  "inputs": {},
  "query": "Explain quantum computing simply",
  "response_mode": "streaming",
  "user": "user-123"
}

Then run:

curl -s -X POST "https://api.dify.ai/v1/chat-messages" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d @/tmp/dify_request.json

Streaming returns Server-Sent Events (SSE) with incremental chunks.

Continue a Conversation

To continue an existing conversation, include the conversation_id from the first response:

Write to /tmp/dify_request.json:

{
  "inputs": {},
  "query": "Tell me more about that",
  "response_mode": "blocking",
  "conversation_id": "{conversation_id}",
  "user": "user-123"
}

Then run:

curl -s -X POST "https://api.dify.ai/v1/chat-messages" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d @/tmp/dify_request.json | jq .

Stop Chat Message Generation

curl -s -X POST "https://api.dify.ai/v1/chat-messages/{task_id}/stop" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d '{"user": "user-123"}' | jq .

Text Completion

Create Completion Message

Write to /tmp/dify_request.json:

{
  "inputs": {
    "text": "Summarize the following: Dify is an open-source LLM app development platform."
  },
  "response_mode": "blocking",
  "user": "user-123"
}

Then run:

curl -s -X POST "https://api.dify.ai/v1/completion-messages" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d @/tmp/dify_request.json | jq .

The inputs object keys depend on the variables configured in your Dify app's prompt template.

Workflow Execution

Execute Workflow (Blocking)

Write to /tmp/dify_request.json:

{
  "inputs": {
    "query": "Analyze this data and provide insights"
  },
  "response_mode": "blocking",
  "user": "user-123"
}

Then run:

curl -s -X POST "https://api.dify.ai/v1/workflows/run" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d @/tmp/dify_request.json | jq .

Response includes workflow_run_id, status, outputs, elapsed_time, and total_tokens.

Execute Workflow (Streaming)

Write to /tmp/dify_request.json:

{
  "inputs": {
    "query": "Generate a report on AI trends"
  },
  "response_mode": "streaming",
  "user": "user-123"
}

Then run:

curl -s -X POST "https://api.dify.ai/v1/workflows/run" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d @/tmp/dify_request.json

Get Workflow Run Detail

curl -s -X GET "https://api.dify.ai/v1/workflows/run/{workflow_run_id}" --header "Authorization: Bearer $DIFY_TOKEN" | jq .

Conversations

List Conversations

curl -s -X GET "https://api.dify.ai/v1/conversations?user=user-123&limit=20" --header "Authorization: Bearer $DIFY_TOKEN" | jq .

Get Conversation History Messages

curl -s -X GET "https://api.dify.ai/v1/messages?user=user-123&conversation_id={conversation_id}&limit=20" --header "Authorization: Bearer $DIFY_TOKEN" | jq .

Delete Conversation

curl -s -X DELETE "https://api.dify.ai/v1/conversations/{conversation_id}" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d '{"user": "user-123"}' | jq .

Rename Conversation

curl -s -X POST "https://api.dify.ai/v1/conversations/{conversation_id}/name" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d '{"name": "My Chat Session", "user": "user-123"}' | jq .

Message Feedback

curl -s -X POST "https://api.dify.ai/v1/messages/{message_id}/feedbacks" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d '{"rating": "like", "user": "user-123"}' | jq .

Rating values: like, dislike, or null (to remove feedback).

Suggested Questions

Get follow-up question suggestions after a message:

curl -s -X GET "https://api.dify.ai/v1/messages/{message_id}/suggested?user=user-123" --header "Authorization: Bearer $DIFY_TOKEN" | jq .

File Upload

Upload a file for use in conversations:

curl -s -X POST "https://api.dify.ai/v1/files/upload" --header "Authorization: Bearer $DIFY_TOKEN" -F "file=@/path/to/file.png" -F "user=user-123" | jq .

Use the returned id in chat messages by adding it to the files array in the request body.

Application Info

Get Application Parameters

curl -s -X GET "https://api.dify.ai/v1/parameters?user=user-123" --header "Authorization: Bearer $DIFY_TOKEN" | jq .

Get Application Meta Info

curl -s -X GET "https://api.dify.ai/v1/meta?user=user-123" --header "Authorization: Bearer $DIFY_TOKEN" | jq .

Knowledge Base Management

Knowledge base APIs use a separate Dataset API key (not the app API key). Generate it from the Knowledge page's API section.

Create Knowledge Base

curl -s -X POST "https://api.dify.ai/v1/datasets" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d '{"name": "My Knowledge Base"}' | jq .

List Knowledge Bases

curl -s -X GET "https://api.dify.ai/v1/datasets?page=1&limit=20" --header "Authorization: Bearer $DIFY_TOKEN" | jq .

Delete Knowledge Base

curl -s -X DELETE "https://api.dify.ai/v1/datasets/{dataset_id}" --header "Authorization: Bearer $DIFY_TOKEN" | jq .

Create Document by Text

Write to /tmp/dify_request.json:

{
  "name": "example-document",
  "text": "This is the content of the document to be indexed.",
  "indexing_technique": "high_quality",
  "process_rule": {
    "mode": "automatic"
  }
}

Then run:

curl -s -X POST "https://api.dify.ai/v1/datasets/{dataset_id}/document/create_by_text" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d @/tmp/dify_request.json | jq .

List Documents in Knowledge Base

curl -s -X GET "https://api.dify.ai/v1/datasets/{dataset_id}/documents?page=1&limit=20" --header "Authorization: Bearer $DIFY_TOKEN" | jq .

Delete Document

curl -s -X DELETE "https://api.dify.ai/v1/datasets/{dataset_id}/documents/{document_id}" --header "Authorization: Bearer $DIFY_TOKEN" | jq .

Query Knowledge Base (Retrieval)

Write to /tmp/dify_request.json:

{
  "query": "What is machine learning?",
  "retrieval_model": {
    "search_method": "semantic_search",
    "reranking_enable": false
  },
  "top_k": 3
}

Then run:

curl -s -X POST "https://api.dify.ai/v1/datasets/{dataset_id}/retrieve" --header "Authorization: Bearer $DIFY_TOKEN" --header "Content-Type: application/json" -d @/tmp/dify_request.json | jq .

Guidelines

1. Each app has its own API key starting with app-. Generate keys from the app's API Access page
2. Knowledge base APIs use a separate key generated from the Knowledge page's API section
3. Use response_mode: "blocking" for simple integrations; use "streaming" for real-time UI
4. Conversation continuity requires passing conversation_id from previous responses
5. The user field is required in most endpoints for usage tracking and rate limiting
6. The inputs keys depend on variables configured in your Dify app's prompt template
7. API conversations are isolated from WebApp conversations and cannot be shared
8. Complex JSON payloads should be written to /tmp/dify_request.json and referenced with -d @/tmp/dify_request.json