docs: document Human Input file inputs and Service API for self-host#826
Merged
Conversation
Cover the Human Input node's file-handling additions in the self-host tree: the Single File and File List field types, how file values render as `[file]` / `[N files]` placeholders in `__rendered_content`, and referencing an upstream file variable in Form Content. Add an API Integration Flow page for the Service API sequence (run, get form, upload via Upload File, submit, resume listening), register it in the self-host nav, add the Single File and File List glossary entries, and refresh the example images. Verified against dify 1.15.0 and graphon 0.5.3. Self-host only; the Cloud tree is updated separately.
Update the Human Input endpoints in the workflow and chatflow Service API specs to dify 1.15.0. Document file-mapping submit inputs, where a `file` or `file-list` value is `{transfer_method: local_file, upload_file_id}` (the id from Upload File) or `{transfer_method: remote_url, url}`, and replace the stale `text_input` type with the real `paragraph`, `select`, `file`, and `file-list` values in both the get-form response and the streaming `human_input_required` event.
Make `expiration_time` nullable, drop the unenforced `action` length and pattern constraints, and align the zh delivery-method term with the product UI (提交方式).
The old description read it as the maximum files per workflow execution. It actually bounds the max-files setting on a single file-upload field, such as a User Input or Human Input File List; the node panel's slider is capped at this value. Reword across en, zh, and ja.
Require an independent subagent audit against the codebase after writing or substantially changing endpoints. The brief pins the dify tag and the pinned graphon version, loads the skill references, and calls out the Service-API-vs-web/console controller distinction so the auditor verifies against the blueprint whose base URL matches the spec's servers.
Following the in-product docs PR (langgenius/dify#37981) and verified against dify 1.15.0 and graphon 0.5.3: a submitted file object carries a `type` from the field's `allowed_file_types`; a `local_file` upload must use the same `user` as the submit, since uploaded files are scoped to that user; and the get-form and submit examples now cover all four input shapes (paragraph, select, file, file-list).
Add two guards to the post-writing code audit: trace opaque request fields to their resolver for ownership and cross-request rules, and diff the spec against the in-product API templates when the endpoint exists there. Add a mechanical example-and-schema consistency pass that checks example keys against schema fields and that every enum and `oneOf` branch is exercised.
dosubot
Bot
added
size:XL
Contributor
There was a problem hiding this comment.
Pull request overview
This PR updates the Dify docs to cover Human Input file inputs and the Service API flow for paused forms across the self-host documentation, including new “API Integration Flow” pages and updated OpenAPI specs.
Changes:
- Expands the Human Input node docs with file-field behavior, examples, and an end-to-end Service API integration flow.
- Updates Workflow/Chatflow OpenAPI specs to reflect current Human Input form shapes, file mappings, and examples.
- Adds supporting updates (env var clarification, glossary terms, nav grouping, and a skill doc update).
Reviewed changes
Copilot reviewed 18 out of 20 changed files in this pull request and generated 25 comments.
Show a summary per file
| File | Description |
|---|---|
| zh/self-host/use-dify/nodes/human-input.mdx | Updates zh Human Input node doc with file fields, API flow link, and a worked example. |
| zh/self-host/use-dify/nodes/hitl-api-integration-flow.mdx | Adds zh API integration flow page for paused Human Input forms. |
| zh/self-host/deploy/configuration/environments.mdx | Clarifies WORKFLOW_FILE_UPLOAD_LIMIT semantics in zh. |
| zh/api-reference/openapi_workflow.json | Updates zh Workflow OpenAPI for Human Input form/get/submit schemas and examples. |
| zh/api-reference/openapi_chatflow.json | Updates zh Chatflow OpenAPI for Human Input form/get/submit schemas and examples. |
| writing-guides/glossary.md | Adds glossary entries for Single File / File List labels. |
| ja/self-host/use-dify/nodes/human-input.mdx | Updates ja Human Input node doc with file fields, API flow link, and a worked example. |
| ja/self-host/use-dify/nodes/hitl-api-integration-flow.mdx | Adds ja API integration flow page for paused Human Input forms. |
| ja/self-host/deploy/configuration/environments.mdx | Clarifies WORKFLOW_FILE_UPLOAD_LIMIT semantics in ja. |
| ja/api-reference/openapi_workflow.json | Updates ja Workflow OpenAPI for Human Input form/get/submit schemas and examples. |
| ja/api-reference/openapi_chatflow.json | Updates ja Chatflow OpenAPI for Human Input form/get/submit schemas and examples. |
| en/self-host/use-dify/nodes/human-input.mdx | Updates en Human Input node doc with file fields, API flow link, and a worked example. |
| en/self-host/use-dify/nodes/hitl-api-integration-flow.mdx | Adds en API integration flow page for paused Human Input forms. |
| en/self-host/deploy/configuration/environments.mdx | Clarifies WORKFLOW_FILE_UPLOAD_LIMIT semantics in en. |
| en/api-reference/openapi_workflow.json | Updates en Workflow OpenAPI for Human Input form/get/submit schemas and examples. |
| en/api-reference/openapi_chatflow.json | Updates en Chatflow OpenAPI for Human Input form/get/submit schemas and examples. |
| docs.json | Groups Human Input pages in nav and registers the new integration-flow page. |
| .claude/skills/dify-docs-api-reference/SKILL.md | Adds a required independent audit step + consistency checklist guidance. |
Comments suppressed due to low confidence (1)
ja/self-host/use-dify/nodes/human-input.mdx:96
- This section repeats the action-ID explanation and shows two very similar screenshots back-to-back, which looks like an accidental duplication.
各ボタンには表示タイトルとアクション ID があります。ボタンがクリックされると、その ID は下流変数 `__action_id`、タイトル（ボタンテキスト）は `__action_value` として利用できます。
<Frame>
</Frame>
💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.
Apply reader-test findings and a code-verified correction to the integration flow page and the workflow/chatflow specs.
- Spell out the submit lifecycle: a successful submit is one-shot (closes the form, resumes the run), a rejected one leaves the form open to retry, and the `action` must be one of the form's actions.
- Note the form's `expiration_time` and that the resumed run streams through to completion.
- Make the remote-file mapping concrete (`{transfer_method: remote_url, url}`).
- Soften the file-upload `user` rule to a consistent-`user` recommendation across the run, upload, and submit (verified: the submit `user` is not matched against the run), in the page and both specs.
- Mirror every change into zh and ja.
Contributor
There was a problem hiding this comment.
Pull request overview
Copilot reviewed 18 out of 20 changed files in this pull request and generated 15 comments.
Comments suppressed due to low confidence (1)
ja/self-host/use-dify/nodes/human-input.mdx:96
- This section repeats the same action-button explanation and repeats the same image in two consecutive blocks (lines 86–90 and 92–95). Remove the duplicate paragraph + frame to avoid redundant content.
各ボタンには表示タイトルとアクション ID があります。ボタンがクリックされると、その ID は下流変数 `__action_id`、タイトル（ボタンテキスト）は `__action_value` として利用できます。
<Frame>
</Frame>
The zh/ja error examples still referenced `comment`; the earlier fix only caught the English message. Match the `feedback` request example.
Contributor
Author
💚 All backports created successfully
Questions ?Please refer to the Backport tool documentation and see the Github Action logs for details |
RiskeyL
added a commit
that referenced
this pull request
Jun 29, 2026
…826) (#827) * docs: document Human Input file inputs and API flow for self-host Cover the Human Input node's file-handling additions in the self-host tree: the Single File and File List field types, how file values render as `[file]` / `[N files]` placeholders in `__rendered_content`, and referencing an upstream file variable in Form Content. Add an API Integration Flow page for the Service API sequence (run, get form, upload via Upload File, submit, resume listening), register it in the self-host nav, add the Single File and File List glossary entries, and refresh the example images. Verified against dify 1.15.0 and graphon 0.5.3. Self-host only; the Cloud tree is updated separately. * docs: align Human Input API with HITL-2 form inputs Update the Human Input endpoints in the workflow and chatflow Service API specs to dify 1.15.0. Document file-mapping submit inputs, where a `file` or `file-list` value is `{transfer_method: local_file, upload_file_id}` (the id from Upload File) or `{transfer_method: remote_url, url}`, and replace the stale `text_input` type with the real `paragraph`, `select`, `file`, and `file-list` values in both the get-form response and the streaming `human_input_required` event. Make `expiration_time` nullable, drop the unenforced `action` length and pattern constraints, and align the zh delivery-method term with the product UI (提交方式). * docs: clarify WORKFLOW_FILE_UPLOAD_LIMIT as a per-field cap The old description read it as the maximum files per workflow execution. It actually bounds the max-files setting on a single file-upload field, such as a User Input or Human Input File List; the node panel's slider is capped at this value. Reword across en, zh, and ja. * feat: add code-audit step to api-reference skill Require an independent subagent audit against the codebase after writing or substantially changing endpoints. The brief pins the dify tag and the pinned graphon version, loads the skill references, and calls out the Service-API-vs-web/console controller distinction so the auditor verifies against the blueprint whose base URL matches the spec's servers. * docs: document file submission details for Human Input API Following the in-product docs PR (langgenius/dify#37981) and verified against dify 1.15.0 and graphon 0.5.3: a submitted file object carries a `type` from the field's `allowed_file_types`; a `local_file` upload must use the same `user` as the submit, since uploaded files are scoped to that user; and the get-form and submit examples now cover all four input shapes (paragraph, select, file, file-list). * feat: harden api-reference audit with data-path and example checks Add two guards to the post-writing code audit: trace opaque request fields to their resolver for ownership and cross-request rules, and diff the spec against the in-product API templates when the endpoint exists there. Add a mechanical example-and-schema consistency pass that checks example keys against schema fields and that every enum and `oneOf` branch is exercised. * docs: address PR review feedback on Human Input docs * docs: clarify Human Input API integration flow Apply reader-test findings and a code-verified correction to the integration flow page and the workflow/chatflow specs. - Spell out the submit lifecycle: a successful submit is one-shot (closes the form, resumes the run), a rejected one leaves the form open to retry, and the `action` must be one of the form's actions. - Note the form's `expiration_time` and that the resumed run streams through to completion. - Make the remote-file mapping concrete (`{transfer_method: remote_url, url}`). - Soften the file-upload `user` rule to a consistent-`user` recommendation across the run, upload, and submit (verified: the submit `user` is not matched against the run), in the page and both specs. - Mirror every change into zh and ja. * fix: correct field name in zh/ja invalid_form_data examples The zh/ja error examples still referenced `comment`; the earlier fix only caught the English message. Match the `feedback` request example. (cherry picked from commit 7694a26)
This file contains hidden or bidirectional Unicode text that may be interpreted or compiled differently than what appears below. To review, open the file in an editor that reveals hidden Unicode characters.
Learn more about bidirectional Unicode characters
Sign up for free
to join this conversation on GitHub.
Already have an account?
Sign in to comment
Add this suggestion to a batch that can be applied as a single commit.This suggestion is invalid because no changes were made to the code.Suggestions cannot be applied while the pull request is closed.Suggestions cannot be applied while viewing a subset of changes.Only one suggestion per line can be applied in a batch.Add this suggestion to a batch that can be applied as a single commit.Applying suggestions on deleted lines is not supported.You must change the existing code in this line in order to create a valid suggestion.Outdated suggestions cannot be applied.This suggestion has been applied or marked resolved.Suggestions cannot be applied from pending reviews.Suggestions cannot be applied on multi-line comments.Suggestions cannot be applied while the pull request is queued to merge.Suggestion cannot be applied right now. Please check back later.
Summary
Documents the Human Input node's file-input support and the Service API for driving paused forms, in the self-host docs tree (English, Chinese, Japanese). Every claim is verified against dify 1.15.0 and graphon 0.5.3.
What's included
User guide (
self-host/use-dify/nodes/human-input.mdx)[file]/[N files]in__rendered_content, and referencing an upstream file variable in Form Content.API Integration Flow page (new)
/v1/files/upload) or attach remote files inline, submit, and resume listening.Human Input Service API specs (
api-reference/openapi_{workflow,chatflow}.json)local_file+upload_file_id, orremote_url+url), each carrying atypefrom the field'sallowed_file_types.useron submit, plus the rule that an uploaded file must be created under that sameuser.paragraph/select/file/file-listinput types in the get-form response and the streaminghuman_input_requiredevent, replacing the staletext_input.Supporting
WORKFLOW_FILE_UPLOAD_LIMITdescription, refreshed example images, and nav registration.Tooling
dify-docs-api-referenceskill with an independent code-audit step (Service-API-vs-web controller distinction, data-path tracing) and an example-and-schema consistency check.Close #783