Skip to content

docs: add async response_mode to workflow API reference #746

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
Umair706 wants to merge 1 commit into
base: main
Choose a base branch
from
Open

docs: add async response_mode to workflow API reference #746

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
109 changes: 105 additions & 4 deletions en/api-reference/openapi_workflow.json
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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": {
Expand Down Expand Up @@ -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",
Expand Down Expand Up @@ -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": [
Expand Down