From f7e4b044582f1e6ceb6cc79d2563c65db8331688 Mon Sep 17 00:00:00 2001 From: Umair706 Date: Thu, 16 Apr 2026 15:20:22 +1000 Subject: [PATCH] docs: add async response_mode to workflow API reference Add documentation for the new `response_mode: "async"` option in the workflow execution endpoints (`POST /workflows/run` and `POST /workflows/{workflow_id}/run`). Changes to `openapi_workflow.json`: - Add `"async"` to the `response_mode` enum with updated description - Add request example for async mode - Add `202 Accepted` response with `WorkflowAsyncResponse` schema - Add `WorkflowAsyncResponse` component schema - Update `200` response descriptions to cover idempotency cache hits Companion to langgenius/dify#35301. --- en/api-reference/openapi_workflow.json | 109 ++++++++++++++++++++++++- 1 file changed, 105 insertions(+), 4 deletions(-) diff --git a/en/api-reference/openapi_workflow.json b/en/api-reference/openapi_workflow.json index 756bf9a38..aa330ce8f 100644 --- a/en/api-reference/openapi_workflow.json +++ b/en/api-reference/openapi_workflow.json @@ -59,6 +59,16 @@ "user": "user_workflow_456" } }, + "async_example": { + "summary": "Request Example - Async mode", + "value": { + "inputs": { + "query": "Process this long-running task" + }, + "response_mode": "async", + "user": "user_workflow_789" + } + }, "with_file_array_variable": { "summary": "Request Example - File array input", "value": { @@ -86,7 +96,7 @@ }, "responses": { "200": { - "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.\n- If `response_mode` is `async` and an `Idempotency-Key` header was provided that matches a previous request, returns `application/json` with the cached `WorkflowAsyncResponse`.", "content": { "application/json": { "schema": { @@ -130,6 +140,31 @@ } } }, + "202": { + "description": "Accepted — returned when `response_mode` is `async`. The workflow has been scheduled for execution. Use the `workflow_run_id` to poll for results via [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail).\n\nSupports an optional `Idempotency-Key` request header (max 64 characters). If the same key is sent again within 24 hours, the server returns `200` with the cached response instead of scheduling a duplicate run.", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowAsyncResponse" + }, + "examples": { + "asyncResponse": { + "summary": "Response Example - Async mode", + "value": { + "task_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "scheduled", + "created_at": 1705407629 + } + } + } + } + } + } + }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Invalid parameter value.", "content": { @@ -275,7 +310,7 @@ }, "responses": { "200": { - "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.", + "description": "Successful response. The content type and structure depend on the `response_mode` parameter in the request.\n\n- If `response_mode` is `blocking`, returns `application/json` with a `WorkflowBlockingResponse` object.\n- If `response_mode` is `streaming`, returns `text/event-stream` with a stream of `ChunkWorkflowEvent` objects.\n- If `response_mode` is `async` and an `Idempotency-Key` header was provided that matches a previous request, returns `application/json` with the cached `WorkflowAsyncResponse`.", "content": { "application/json": { "schema": { @@ -313,6 +348,31 @@ } } }, + "202": { + "description": "Accepted — returned when `response_mode` is `async`. The workflow has been scheduled for execution. Use the `workflow_run_id` to poll for results via [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail).", + "content": { + "application/json": { + "schema": { + "$ref": "#/components/schemas/WorkflowAsyncResponse" + }, + "examples": { + "asyncResponse": { + "summary": "Response Example - Async mode", + "value": { + "task_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_run_id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "data": { + "id": "fb47b2e6-5e43-4f90-be01-d5c5a088d156", + "workflow_id": "7c3e33d4-2a8b-4e5f-9b1a-d3c6e8f12345", + "status": "scheduled", + "created_at": 1705407629 + } + } + } + } + } + } + }, "400": { "description": "- `not_workflow_app` : App mode does not match the API route.\n- `bad_request` : Workflow is a draft or has an invalid ID format.\n- `provider_not_initialize` : No valid model provider credentials found.\n- `provider_quota_exceeded` : Model provider quota exhausted.\n- `model_currently_not_support` : Current model unavailable.\n- `completion_request_error` : Workflow execution request failed.\n- `invalid_param` : Required parameter missing or invalid.", "content": { @@ -1617,9 +1677,10 @@ "type": "string", "enum": [ "streaming", - "blocking" + "blocking", + "async" ], - "description": "Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), or `streaming` for Server-Sent Events. When omitted, defaults to blocking behavior." + "description": "Response mode. Use `blocking` for synchronous responses (Cloudflare timeout is `100 s`), `streaming` for Server-Sent Events, or `async` for fire-and-forget execution that returns immediately with a `workflow_run_id` for polling. When omitted, defaults to blocking behavior." }, "user": { "type": "string", @@ -1690,6 +1751,46 @@ } } }, + "WorkflowAsyncResponse": { + "type": "object", + "description": "Returned with HTTP 202 when `response_mode` is `async`. The workflow has been accepted and scheduled for background execution. Poll for results using the `workflow_run_id` with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail). The status will progress from `scheduled` → `running` → `succeeded` / `failed`.", + "properties": { + "task_id": { + "type": "string", + "format": "uuid", + "description": "Task ID, same as `workflow_run_id` for async requests." + }, + "workflow_run_id": { + "type": "string", + "format": "uuid", + "description": "Persistent identifier for this workflow run. Use this with [Get Workflow Run Detail](/api-reference/workflows/get-workflow-run-detail) to poll for results." + }, + "data": { + "type": "object", + "properties": { + "id": { + "type": "string", + "format": "uuid", + "description": "Workflow run ID." + }, + "workflow_id": { + "type": "string", + "format": "uuid", + "description": "ID of the workflow that was executed." + }, + "status": { + "type": "string", + "enum": ["scheduled"], + "description": "Initial status. Will transition to `running`, then `succeeded` or `failed`." + }, + "created_at": { + "type": "integer", + "description": "Unix timestamp of when the run was created." + } + } + } + } + }, "ChunkWorkflowEvent": { "type": "object", "required": [