Skip to content

docs: add async response_mode to workflow API reference#746

Open
Umair706 wants to merge 1 commit intolanggenius:mainfrom
Umair706:docs/async-workflow-api
Open

docs: add async response_mode to workflow API reference#746
Umair706 wants to merge 1 commit intolanggenius:mainfrom
Umair706:docs/async-workflow-api

Conversation

@Umair706
Copy link
Copy Markdown

Summary

Add documentation for the new response_mode: "async" option in the workflow execution API, introduced in langgenius/dify#35301.

Changes to en/api-reference/openapi_workflow.json

  • Add "async" to the response_mode enum in WorkflowExecutionRequest schema
  • Update response_mode field description to explain async behavior
  • Add request example for async mode
  • Add 202 Accepted response to both /workflows/run and /workflows/{workflow_id}/run
  • Add WorkflowAsyncResponse component schema (returns task_id, workflow_run_id, and data with status: "scheduled")
  • Update 200 response descriptions to cover idempotency cache hits (duplicate async requests return 200 instead of 202)

How async mode works

  1. Client sends POST /v1/workflows/run with "response_mode": "async"
  2. Server returns 202 Accepted immediately with a workflow_run_id
  3. Client polls GET /v1/workflows/run/{workflow_run_id} for results
  4. Status progresses: scheduledrunningsucceeded / failed
  5. Optional Idempotency-Key header prevents duplicate executions on retry

Test plan

  • Verify openapi_workflow.json is valid JSON
  • Verify Mintlify renders the new enum value, 202 response, and schema correctly

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.
@Umair706 Umair706 requested a review from RiskeyL as a code owner April 16, 2026 05:20
@dosubot dosubot Bot added size:XS This PR changes 0-9 lines, ignoring generated files. documentation Improvements or additions to documentation labels Apr 16, 2026
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation size:XS This PR changes 0-9 lines, ignoring generated files.

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant