​
Execute Workflow

POST /workflows/run

Execute a workflow. Cannot be executed without a published workflow.

​
Request Body

  • inputs (object) Required

    • Allows passing variable values defined by the App
    • inputs parameter contains multiple key/value pairs
    • Text generation applications require at least one key/value pair

  • response_mode (string) Required Return response mode, supports:

    • streaming Streaming mode (recommended)
    • blocking Blocking mode

  • user (string) Required

    • User identifier, used to define the identity of end users
    • Rules defined by developers, must ensure user identifiers are unique within the application

  • files (array[object]) Optional File list, suitable for inputting files (images) combined with text understanding and answering questions

    • type (string) Supported type: image
    • transfer_method (string) Transfer method, remote_url / local_file
    • url (string) Image URL
    • upload_file_id (string) Upload file ID

​
Response

​
CompletionResponse (blocking mode)

  • task_id (string) Task ID
  • workflow_run_id (string) Workflow execution ID
  • data (object)
    • id (string) Workflow execution ID
    • workflow_id (string) Associated Workflow ID
    • status (string) Execution status
    • outputs (json) Output content
    • error (string) Error reason
    • elapsed_time (float) Time consumed
    • total_tokens (int) Total tokens used
    • total_steps (int) Total steps
    • created_at (timestamp) Run time
    • finished_at (timestamp) End time

​
ChunkCompletionResponse (streaming mode)

Streaming event types include:

  1. workflow_started
{
  "task_id": "string",
  "workflow_run_id": "string",
  "event": "workflow_started",
  "data": {
    "id": "string",
    "workflow_id": "string",
    "sequence_number": 1,
    "created_at": "timestamp"
  }
}
  1. node_started
{
  "task_id": "string",
  "workflow_run_id": "string",
  "event": "node_started",
  "data": {
    "id": "string",
    "node_id": "string",
    "node_type": "string",
    "index": 0,
    "predecessor_node_id": "string",
    "inputs": [],
    "parallel_id": "string",
    "parallel_start_node_id": "string",
    "created_at": "timestamp"
  }
}
  1. node_finished
{
  "task_id": "string",
  "workflow_run_id": "string",
  "event": "node_finished",
  "data": {
    "id": "string",
    "node_id": "string",
    "node_type": "string",
    "index": 0,
    "predecessor_node_id": "string",
    "inputs": [],
    "process_data": {},
    "outputs": {},
    "status": "string",
    "error": "string",
    "elapsed_time": 0.0,
    "execution_metadata": {
      "total_tokens": 0,
      "total_price": "0.00",
      "currency": "USD"
    },
    "parallel_id": "string",
    "parallel_start_node_id": "string",
    "created_at": "timestamp"
  }
}
  1. parallel_branch_started/finished
{
  "task_id": "string",
  "workflow_run_id": "string",
  "event": "parallel_branch_started",
  "data": {
    "parallel_id": "string",
    "parallel_start_node_id": "string",
    "parent_parallel_id": "string",
    "parent_parallel_start_node_id": "string", 
    "iteration_id": "string",
    "created_at": "timestamp"
  }
}
  1. iteration_started/next/completed
{
  "task_id": "string",
  "workflow_run_id": "string",
  "event": "iteration_started",
  "data": {
    "id": "string",
    "node_id": "string",
    "node_type": "string",
    "title": "string",
    "metadata": {},
    "inputs": [],
    "parallel_id": "string",
    "parallel_start_node_id": "string",
    "created_at": "timestamp"
  }
}
  1. workflow_finished
{
  "task_id": "string",
  "workflow_run_id": "string",
  "event": "workflow_finished",
  "data": {
    "id": "string",
    "workflow_id": "string",
    "status": "string",
    "outputs": {},
    "error": "string",
    "elapsed_time": 0.0,
    "total_tokens": 0,
    "total_steps": 0,
    "created_at": "timestamp",
    "finished_at": "timestamp"
  }
}
  1. text_chunk/text_replace
{
  "task_id": "string",
  "workflow_run_id": "string",
  "event": "text_chunk",
  "data": {
    "text": "string"
  }
}

​
Error Codes

  • 400 invalid_param - Invalid parameter input
  • 400 app_unavailable - App configuration unavailable
  • 400 provider_not_initialize - No available model credentials configured
  • 400 provider_quota_exceeded - Insufficient model call quota
  • 400 model_currently_not_support - Current model unavailable
  • 400 completion_request_error - Text generation failed
  • 500 - Internal server error

​
Examples

Request example:

curl -X POST 'https://api.dify.ai/v1/workflows/run' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "inputs": {
        "query": "hello world."
    },
    "response_mode": "streaming",
    "user": "abc-123",
    "files": [
      {
        "type": "image",
        "transfer_method": "remote_url",
        "url": "https://cloud.dify.ai/logo/logo-site.png"
      }
    ]
}'

​
Stop Workflow

POST /workflows/:task_id/stop

Only supports streaming mode.

​
Path Parameters

  • task_id (string) Task ID

​
Request Body

  • user (string) Required - User identifier, must be consistent with the user passed when executing the workflow

​
Response

  • result (string) Fixed return “success”

​
Example

Request example:

curl -X POST 'https://cloud.dify.ai/v1/workflows/:task_id/stop' \
-H 'Authorization: Bearer {api_key}' \
-H 'Content-Type: application/json' \
--data-raw '{
    "user": "abc-123"
}'