docs: HITL Service API polish and 1.14 release follow-ups by RiskeyL · Pull Request #756 · langgenius/dify-docs

RiskeyL · 2026-04-27T06:41:28Z

Summary

HITL Service API documentation polish. Tighten the Get/Submit/Stream Human Input Form endpoint descriptions across the workflow and chatflow specs (EN/ZH/JA) so each one surfaces only the essentials and cross-references the rest of the flow. On the Human Input node help page, replace the standalone "Drive Human Input via the API" section with a single Info callout nested under the Web app delivery bullet, pointing to the Service API reference. Orchestration prose belongs in the API reference, not on a node configuration page.
Streaming response descriptions reorganized. Restructure the SSE description on every streaming endpoint (POST /workflows/run plus its versioned variant, POST /chat-messages, and GET /workflow/{task_id}/events) from one dense paragraph into three topical sections: Parsing, Stream lifecycle, and Human Input events. Drop the redundant lead sentence and the dead ChunkWorkflowEvent / ChunkChatEvent reference (Mintlify doesn't surface schema names from prose). Add workflow_paused to the workflow-spec lifecycle paragraph; verified against api/core/app/apps/workflow/generate_task_pipeline.py where the pipeline explicitly breaks on QueueWorkflowPausedEvent.
Schema constraint correctness. Move HITL UserAction id and title length/pattern constraints out of description parentheticals and into machine-readable schema fields (maxLength plus pattern on id, maxLength on title) across all six API spec files. Verified against graphon/nodes/human_input/entities.py.
API reference link convention. Amend writing-guides/formatting-guide.md Internal Links section to carve out an exception: /api-reference/<tag>/<endpoint> links omit the language prefix in all three languages (Mintlify auto-routes to the active locale; a prefix breaks the auto-routing).
Marketplace publish flow update. Drop the "1.14 beta only" callout from publish-to-marketplace.mdx and update the click path to "Publish > Publish Update > Publish to Marketplace" to match the current UI (EN/ZH/JA).

mintlify · 2026-04-27T06:41:32Z

Preview deployment for your docs. Learn more about Mintlify Previews.

Project	Status	Preview	Updated (UTC)
dify-core-product	🟢 Ready	View Preview	Apr 27, 2026, 6:43 AM

💡 Tip: Enable Workflows to automatically generate PRs for you.

Copilot

Pull request overview

This PR polishes Dify’s HITL (Human Input) Service API documentation and 1.14 follow-ups across EN/ZH/JA, including reorganized SSE streaming docs, more machine-readable schema constraints, updated Marketplace publish steps, and an env-doc verifier enhancement for intentionally ignored variables.

Changes:

Reworked SSE streaming descriptions (parsing, lifecycle, Human Input events) and added Human Input endpoints + schemas to workflow/chatflow OpenAPI specs.
Updated Human Input node docs to point readers to the Service API reference (instead of embedding orchestration prose), and refreshed Marketplace publish UI steps across locales.
Improved self-host env var docs (new Redis/Celery/VectorDB knobs) and enhanced the env-doc verifier with an ignore list mechanism.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 6 comments.

Show a summary per file

File	Description
zh/use-dify/publish/publish-to-marketplace.mdx	Updates Marketplace publish click-path; removes 1.14 beta-only callout.
zh/use-dify/nodes/human-input.mdx	Replaces embedded API orchestration section with an Info callout linking to API reference.
zh/self-host/configuration/environments.mdx	Syncs/extends env var reference (Redis resilience, worker healthcheck, Baidu VDB, etc.) and formatting.
zh/api-reference/openapi_workflow.json	Refines SSE prose; adds Human Input form endpoints + tag and schema constraint fields.
zh/api-reference/openapi_knowledge.json	Marks fields nullable where applicable; expands datasource plugin listing schema.
zh/api-reference/openapi_chatflow.json	Refines SSE prose; adds Human Input form endpoints + tag and schema constraint fields.
writing-guides/formatting-guide.md	Adds explicit internal-link convention for API reference links (no locale prefix).
ja/use-dify/publish/publish-to-marketplace.mdx	Updates Marketplace publish click-path; removes 1.14 beta-only callout.
ja/use-dify/nodes/human-input.mdx	Adds Service API Info callout under Web app delivery; general copy/format tweaks.
ja/api-reference/openapi_workflow.json	Refines SSE prose; adds Human Input form endpoints + tag and schema constraint fields.
ja/api-reference/openapi_knowledge.json	Marks fields nullable where applicable; expands datasource plugin listing schema.
ja/api-reference/openapi_chatflow.json	Refines SSE prose; adds Human Input form endpoints + tag and schema constraint fields.
en/use-dify/publish/publish-to-marketplace.mdx	Updates Marketplace publish click-path; removes 1.14 beta-only callout.
en/use-dify/nodes/human-input.mdx	Adds Service API Info callout under Web app delivery; whitespace cleanup.
en/self-host/configuration/environments.mdx	Syncs/extends env var reference (Redis resilience, worker healthcheck, Baidu VDB, etc.) and formatting.
en/api-reference/openapi_workflow.json	Refines SSE prose; adds Human Input form endpoints + tag and schema constraint fields.
en/api-reference/openapi_knowledge.json	Marks fields nullable where applicable; expands datasource plugin listing schema.
en/api-reference/openapi_chatflow.json	Refines SSE prose; adds Human Input form endpoints + tag and schema constraint fields.
.claude/skills/dify-docs-env-vars/verify-env-docs.py	Adds `--ignored` support and ignores list for missing/extra var checks.
.claude/skills/dify-docs-env-vars/ignored-vars.md	New curated list of variables intentionally excluded from env docs (with reasons/sources).
.claude/skills/dify-docs-env-vars/deep-dive.md	Adds 1.14 env var deep-dive notes and traceability.
.claude/skills/dify-docs-env-vars/SKILL.md	Documents the new ignored-vars workflow for the verifier.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

* docs: sync App Toolkit page with follow-up settings PR and UI labels * fix: correct CJK format linter false positives * chore: broaden post-writing audit scope to whole documents * docs: address Copilot review on PR #754 Restore the Tab titles rule in formatting-zh.md, which had been trimmed to a stub. Drop the First-Mention Rule entry from the terminology-check skill's Output Format so the report sections match the Checks to Perform sections (the corresponding check was removed earlier). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com>

* docs: add workflow collaboration user guide * docs: tighten style and formatting guides * docs: avoid "please" in zh refer-to phrases * fix: add CJK-Latin spacing in translation notice templates * docs: add env var coordination to dify-docs-guides skill * docs: document collaboration environment variables * style: trim collaboration env var descriptions for consistency * docs: add zoom menu tip for hiding comments and cursors * docs: sync collaboration UI labels after upstream localization

The three HITL event schemas (StreamEventHumanInputRequired, StreamEventHumanInputFormFilled, StreamEventHumanInputFormTimeout) declared `workflow_run_id` inside `data.properties`, but `HumanInputRequiredResponse` in `api/core/app/entities/task_entities.py` defines `workflow_run_id` only as a top-level field on the response (alongside `event` and `task_id`); its inner `Data` class doesn't carry one. The OpenAPI spec already provides top-level `workflow_run_id` via the `$ref: StreamEventBase` in the `allOf` composition, so the inline duplicate was a phantom field that doesn't exist in the actual payload. Remove the inline `workflow_run_id` from `data.properties` in all three HITL event schemas across all six spec files. This relies on `StreamEventBase` to provide `workflow_run_id` at the top level via composition, matching how every other event schema in this spec handles it (e.g., `StreamEventWorkflowStarted`). Reported by Copilot on PR #756.

…759) * docs: rewrite orchestration logic and extend workflow-chatflow overview * translate: update zh and ja for orchestration logic and overview * docs: refine orchestration logic node reuse section * docs: clarify MAX_TREE_DEPTH env var description * fix: align zh title and body references with the glossary UI label * fix: align EN node reuse text with zh/ja translations (User Input exception) Agent-Logs-Url: https://github.com/langgenius/dify-docs/sessions/00e54676-8a43-4b6f-99f8-fef2495b054f Co-authored-by: RiskeyL <36894937+RiskeyL@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Copilot

Pull request overview

Copilot reviewed 39 out of 41 changed files in this pull request and generated 7 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

…ferences

The three HITL event schemas (StreamEventHumanInputRequired, StreamEventHumanInputFormFilled, StreamEventHumanInputFormTimeout) declared `workflow_run_id` inside `data.properties`, but `HumanInputRequiredResponse` in `api/core/app/entities/task_entities.py` defines `workflow_run_id` only as a top-level field on the response (alongside `event` and `task_id`); its inner `Data` class doesn't carry one. The OpenAPI spec already provides top-level `workflow_run_id` via the `$ref: StreamEventBase` in the `allOf` composition, so the inline duplicate was a phantom field that doesn't exist in the actual payload. Remove the inline `workflow_run_id` from `data.properties` in all three HITL event schemas across all six spec files. This relies on `StreamEventBase` to provide `workflow_run_id` at the top level via composition, matching how every other event schema in this spec handles it (e.g., `StreamEventWorkflowStarted`). Reported by Copilot on PR #756.

Copilot

Pull request overview

Copilot reviewed 46 out of 49 changed files in this pull request and generated 6 comments.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Copilot · 2026-04-27T08:12:49Z

+            "description": "元のワークフロー実行リクエストで返されたワークフロー実行 ID。"
+          },
+          {
+            "name": "user",
+            "in": "query",


Chatflow 仕様の /workflow/{task_id}/events で、task_id が「元のワークフロー実行リクエストで返されたワークフロー実行 ID」と説明されていますが、この仕様全体では task_id はチャット系エンドポイントが発行する ID です。呼び出し元が渡すべき ID の出所を、チャット側のリクエストに合わせて表現を修正してください。

Copilot · 2026-04-27T08:12:50Z

+            "description": "Workflow run ID returned by the original workflow run request."
+          },
+          {
+            "name": "user",
+            "in": "query",


In the Chatflow spec, the task_id path parameter is described as a workflow run ID “returned by the original workflow run request”, which doesn’t match the rest of this spec (where task_id is issued by chat endpoints). Please reword these parameter descriptions to reference the originating chat request and clarify exactly which ID callers should pass here.

Copilot · 2026-04-27T08:12:50Z

+            "description": "原始工作流运行请求返回的工作流运行 ID。"
+          },
+          {
+            "name": "user",
+            "in": "query",


在 Chatflow 规范里，/workflow/{task_id}/events 的 task_id 参数描述为“原始工作流运行请求返回的工作流运行 ID”，但该文件上下文里 task_id 通常来自对话接口。建议统一表述：明确这里应传入哪个请求返回的 ID，并避免将其描述为“工作流运行请求”。

The /api-reference/... URL convention (no language prefix, derived from OpenAPI tag/summary) generates pages that Mintlify auto-builds rather than from filesystem MDX files, so the existing filesystem resolution logic flags every such link as broken. Skip both filesystem-existence and anchor validation for any URL containing /api-reference/, mirroring the existing anchor_check_skipped behaviour. The convention is documented in writing-guides/formatting-guide.md. Caveat: typos in tag or summary slugs will now pass silently. A follow-up could parse the OpenAPI specs to validate against the real tag/summary kebab pairs if hand-written api-reference links become common enough to warrant it.

Inline link [CORS設定](#cors 設定) used a literal space, but the heading "CORS 設定" slugifies to "cors-設定" (whitespace replaced with hyphen). Update the anchor to #cors-設定.

…ode framing

* feat: add env var ignore-list consumed by the verifier * docs: add 1.14 env vars and correct drifted defaults * fix: correct knowledge pipeline datasource-plugins response in api references * chore: record 1.14 env var traces in deep-dive * docs: update HITL Service API documentation * docs: clarify /api-reference/ link convention in formatting guide * docs: update marketplace publish flow * fix: drop duplicate workflow_run_id from HITL event data schemas The three HITL event schemas (StreamEventHumanInputRequired, StreamEventHumanInputFormFilled, StreamEventHumanInputFormTimeout) declared `workflow_run_id` inside `data.properties`, but `HumanInputRequiredResponse` in `api/core/app/entities/task_entities.py` defines `workflow_run_id` only as a top-level field on the response (alongside `event` and `task_id`); its inner `Data` class doesn't carry one. The OpenAPI spec already provides top-level `workflow_run_id` via the `$ref: StreamEventBase` in the `allOf` composition, so the inline duplicate was a phantom field that doesn't exist in the actual payload. Remove the inline `workflow_run_id` from `data.properties` in all three HITL event schemas across all six spec files. This relies on `StreamEventBase` to provide `workflow_run_id` at the top level via composition, matching how every other event schema in this spec handles it (e.g., `StreamEventWorkflowStarted`). Reported by Copilot on PR #756. * fix: address Copilot's review comments * feat: skip api-reference paths in internal link checker The /api-reference/... URL convention (no language prefix, derived from OpenAPI tag/summary) generates pages that Mintlify auto-builds rather than from filesystem MDX files, so the existing filesystem resolution logic flags every such link as broken. Skip both filesystem-existence and anchor validation for any URL containing /api-reference/, mirroring the existing anchor_check_skipped behaviour. The convention is documented in writing-guides/formatting-guide.md. Caveat: typos in tag or summary slugs will now pass silently. A follow-up could parse the OpenAPI specs to validate against the real tag/summary kebab pairs if hand-written api-reference links become common enough to warrant it. * fix: correct CORS anchor in ja environments page Inline link [CORS設定](#cors 設定) used a literal space, but the heading "CORS 設定" slugifies to "cors-設定" (whitespace replaced with hyphen). Update the anchor to #cors-設定. * fix: align datasource-plugins is_published and 200 description with node framing * fix: clarify chatflow stream workflow events task_id origin * docs: address HITL Service API reader-test feedback

* docs: sync App Toolkit with dify#35442 follow-up settings (#757) * docs: sync App Toolkit page with follow-up settings PR and UI labels * fix: correct CJK format linter false positives * chore: broaden post-writing audit scope to whole documents * docs: address Copilot review on PR #754 Restore the Tab titles rule in formatting-zh.md, which had been trimmed to a stub. Drop the First-Mention Rule entry from the terminology-check skill's Output Format so the report sections match the Checks to Perform sections (the corresponding check was removed earlier). Co-Authored-By: Claude Opus 4.7 (1M context) <noreply@anthropic.com> --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> * docs: document workflow collaboration feature (#758) * docs: add workflow collaboration user guide * docs: tighten style and formatting guides * docs: avoid "please" in zh refer-to phrases * fix: add CJK-Latin spacing in translation notice templates * docs: add env var coordination to dify-docs-guides skill * docs: document collaboration environment variables * style: trim collaboration env var descriptions for consistency * docs: add zoom menu tip for hiding comments and cursors * docs: sync collaboration UI labels after upstream localization * docs: rewrite orchestration logic for cross-workflow node copy-paste (#759) * docs: rewrite orchestration logic and extend workflow-chatflow overview * translate: update zh and ja for orchestration logic and overview * docs: refine orchestration logic node reuse section * docs: clarify MAX_TREE_DEPTH env var description * fix: align zh title and body references with the glossary UI label * fix: align EN node reuse text with zh/ja translations (User Input exception) Agent-Logs-Url: https://github.com/langgenius/dify-docs/sessions/00e54676-8a43-4b6f-99f8-fef2495b054f Co-authored-by: RiskeyL <36894937+RiskeyL@users.noreply.github.com> --------- Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com> * docs: note HTTPS requirement for cross-workflow node paste (#761) * docs: HITL Service API polish and 1.14 release follow-ups (#760) * feat: add env var ignore-list consumed by the verifier * docs: add 1.14 env vars and correct drifted defaults * fix: correct knowledge pipeline datasource-plugins response in api references * chore: record 1.14 env var traces in deep-dive * docs: update HITL Service API documentation * docs: clarify /api-reference/ link convention in formatting guide * docs: update marketplace publish flow * fix: drop duplicate workflow_run_id from HITL event data schemas The three HITL event schemas (StreamEventHumanInputRequired, StreamEventHumanInputFormFilled, StreamEventHumanInputFormTimeout) declared `workflow_run_id` inside `data.properties`, but `HumanInputRequiredResponse` in `api/core/app/entities/task_entities.py` defines `workflow_run_id` only as a top-level field on the response (alongside `event` and `task_id`); its inner `Data` class doesn't carry one. The OpenAPI spec already provides top-level `workflow_run_id` via the `$ref: StreamEventBase` in the `allOf` composition, so the inline duplicate was a phantom field that doesn't exist in the actual payload. Remove the inline `workflow_run_id` from `data.properties` in all three HITL event schemas across all six spec files. This relies on `StreamEventBase` to provide `workflow_run_id` at the top level via composition, matching how every other event schema in this spec handles it (e.g., `StreamEventWorkflowStarted`). Reported by Copilot on PR #756. * fix: address Copilot's review comments * feat: skip api-reference paths in internal link checker The /api-reference/... URL convention (no language prefix, derived from OpenAPI tag/summary) generates pages that Mintlify auto-builds rather than from filesystem MDX files, so the existing filesystem resolution logic flags every such link as broken. Skip both filesystem-existence and anchor validation for any URL containing /api-reference/, mirroring the existing anchor_check_skipped behaviour. The convention is documented in writing-guides/formatting-guide.md. Caveat: typos in tag or summary slugs will now pass silently. A follow-up could parse the OpenAPI specs to validate against the real tag/summary kebab pairs if hand-written api-reference links become common enough to warrant it. * fix: correct CORS anchor in ja environments page Inline link [CORS設定](#cors 設定) used a literal space, but the heading "CORS 設定" slugifies to "cors-設定" (whitespace replaced with hyphen). Update the anchor to #cors-設定. * fix: align datasource-plugins is_published and 200 description with node framing * fix: clarify chatflow stream workflow events task_id origin * docs: address HITL Service API reader-test feedback --------- Co-authored-by: Claude Opus 4.7 (1M context) <noreply@anthropic.com> Co-authored-by: copilot-swe-agent[bot] <198982749+Copilot@users.noreply.github.com>

Copilot AI review requested due to automatic review settings April 27, 2026 06:41

dosubot Bot added size:XL This PR changes 500-999 lines, ignoring generated files. documentation Improvements or additions to documentation labels Apr 27, 2026

Copilot started reviewing on behalf of RiskeyL April 27, 2026 06:42 View session

mintlify Bot deployed to staging April 27, 2026 06:43 View deployment

Copilot AI reviewed Apr 27, 2026

View reviewed changes

RiskeyL and others added 2 commits April 27, 2026 14:58

mintlify Bot deployed to staging April 27, 2026 07:16 View deployment

Copilot AI review requested due to automatic review settings April 27, 2026 07:29

RiskeyL force-pushed the docs/1.14-check branch from ff037ce to 56f1b33 Compare April 27, 2026 07:29

Copilot started reviewing on behalf of RiskeyL April 27, 2026 07:30 View session

mintlify Bot deployed to staging April 27, 2026 07:32 View deployment

feat: add env var ignore-list consumed by the verifier

2421d7d

Copilot AI reviewed Apr 27, 2026

View reviewed changes

RiskeyL added 7 commits April 27, 2026 15:37

docs: add 1.14 env vars and correct drifted defaults

7054f99

fix: correct knowledge pipeline datasource-plugins response in api re…

efd80f1

…ferences

chore: record 1.14 env var traces in deep-dive

69f965d

docs: update HITL Service API documentation

5c4c179

docs: clarify /api-reference/ link convention in formatting guide

42a9c27

docs: update marketplace publish flow

469e410

RiskeyL force-pushed the docs/1.14-check branch from 56f1b33 to 0efba06 Compare April 27, 2026 07:37

mintlify Bot deployed to staging April 27, 2026 07:39 View deployment

fix: address Copilot's review comments

3be42b5

Copilot AI review requested due to automatic review settings April 27, 2026 08:07

Copilot started reviewing on behalf of RiskeyL April 27, 2026 08:07 View session

mintlify Bot deployed to staging April 27, 2026 08:09 View deployment

Copilot AI reviewed Apr 27, 2026

View reviewed changes

RiskeyL added 4 commits April 27, 2026 16:42

fix: correct CORS anchor in ja environments page

a1785b8

Inline link [CORS設定](#cors 設定) used a literal space, but the heading "CORS 設定" slugifies to "cors-設定" (whitespace replaced with hyphen). Update the anchor to #cors-設定.

fix: align datasource-plugins is_published and 200 description with n…

8db25a2

…ode framing

fix: clarify chatflow stream workflow events task_id origin

4c2905d

RiskeyL closed this Apr 27, 2026

mintlify Bot deployed to staging April 27, 2026 09:49 View deployment

Conversation

RiskeyL commented Apr 27, 2026

Summary

Uh oh!

mintlify Bot commented Apr 27, 2026 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Reviewed changes

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI left a comment

Choose a reason for hiding this comment

Pull request overview

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Copilot AI Apr 27, 2026

Choose a reason for hiding this comment

Uh oh!

Reviewers

Assignees

Labels

Projects

Milestone

Development

Uh oh!

2 participants

mintlify Bot commented Apr 27, 2026 •

edited

Loading