mirror of
https://github.com/langgenius/dify-docs.git
synced 2026-07-22 12:25:45 -04:00
fix/workflow-version-403
4 Commits
| Author | SHA1 | Message | Date | |
|---|---|---|---|---|
 RiskeyL
|
ccebcfd721 |
docs: document the workflow-version 403 for Sandbox plans
Dify 1.16.0 gates running a specific published workflow version behind paid plans on Cloud (dify#38662 for Workflow apps, dify#38892 for Chatflow workflow_id pinning). Adds the 403 with its trigger and verbatim wire message to Run Workflow by ID and Send Chat Message, a plan note on the workflow_id request field, and the plan-gate Note on the Cloud version-control guide. |
||
|
Riskey
|
a1e7a7dcb3 |
feat: finish API reference Phase 1: code audit and readability overhaul (#857) (#858)
* feat: retire the merge pipeline and delete the legacy source specs
openapi_service.json is now the spec of record per language, edited directly. The build/relink modes, resolutions.json, and overrides/ that consolidated the five per-app-type specs are recoverable from git history when Phase 2 rebuilds the spec from the upstream-generated source.
* fix: make parity_check exit nonzero on failures
* docs: document the direct-edit spec workflow in skills and translation guides
* fix: correct the Service API reference against the code-verified audit
Applies the confirmed findings of a full per-operation audit against dify 3c8e0e2113 / graphon 0.6.0: 9 factual errors (availability lines, phantom fields, wrong enum values, inert parameters, wrong error messages), ~33 omitted-error and example-accuracy gaps, the rate_limit_error recharacterization, provider-identifier format documentation, and New Agent availability on the endpoints its Chat Features support (verified end-to-end in code).
* docs: document New Agent's full endpoint surface in the API guides
* translate: propagate the Service API audit fixes to zh and ja
* docs: rewrite Upload File as the readability pilot
Worked example of the API readability standard: contract-first description, facts on the fields (category size limits with env-var link, blacklist rule), real error triggers (415 corrected to its actual cause), template user sentence, source links on sourceable values, and a hand-written multipart cURL sample. Applied to en/zh/ja.
* docs: update spec-conventions for the live link scheme and code samples
* docs: apply the readability standard across the Service API reference
Rewrites all 82 operations to the agreed standard in en/zh/ja: contract-first descriptions, facts on the fields, trigger-led error bullets, template sentences (user, pagination, provider identifiers), source links on sourceable values, guide links instead of inline concept re-explanations, cURL samples where the playground autogen fails (multipart, SSE), a paragraph ceiling everywhere, and restructured streaming narratives (events-by-app-type map; details stay in the event tables). Also folds in two fact corrections surfaced during review: the legacy securitySchemes text and the stale Cloudflare-timeout claim in response_mode, now using the hedged edge-proxy wording.
* docs: codify the readability standard and audit method in the API skill
* fix: apply the audit-verified corrections deferred from the readability pass
Small factual items evidenced in the audit findings that the readability pass could not touch under its fact-freeze: real wire messages (audio 413, type_mismatch number, dynamic run-by-id 404, werkzeug 500/403 strings, annotation 404 punctuation), schema precision (format: uuid, minimum: 1, six missing Get Available Models response fields), and behavioral completeness (document download/zip/delete 404 message variants, tag_ids silent-ignore note, request-scoped batch-metadata lock wording, reasoning_chunk message_id: null, form default key absent not null). Applied to en/zh/ja; parity 0.
* fix: make spec checkers target openapi_service.json explicitly
After the legacy specs were deleted, the openapi_*.json globs in parity_check and lint_specs would silently pass (match nothing, report 0 issues, exit 0) if the spec of record went missing, and would pick up unintended future openapi_*.json files. Both now name openapi_service.json per language and exit 1 when it is absent.
* fix: address Copilot review on pipeline tooling and example titles
Normalizes example summary separators to the dominant "Request Example - Mode" form (the convention doc had drifted, and 4 em-dash outliers existed per language); lint_specs no longer re-reads the spec it already loaded; all spec reads use explicit UTF-8; coverage_matrix and swagger_diff target openapi_service.json explicitly; README and docstring usage resolve DOCS from the git root so the commands work from any directory.
* fix: use context managers for all pipeline file reads
Copilot flagged unclosed handles in the three checkers; applied consistently across all five pipeline scripts (merge_specs and coverage_matrix had the same pattern unflagged).
* fix: report missing spec ops as coverage failures instead of crashing
* fix: print the full relative path in the parity missing-file message
(cherry picked from commit
|
||
|
RiskeyL
|
31cf2ff1ab |
fix: document both New Agent reply events in the streaming contract
The New Agent guide said replies stream as agent_message; the Send Chat Message SSE reference and the streaming guide said message. Verified against dify feat/agent-v2 (agent_app/app_runner.py and its unit tests): both fire — the reply streams incrementally as agent_message deltas, then the turn closes with a single message event carrying the complete answer, then message_end, with agent_thought alongside throughout. Document the full sequence on all three surfaces and tell clients to treat the closing message as the final answer rather than appending it. en/zh/ja; merged specs regenerated via the API pipeline (build + wire, coverage clean). |
||
|
Riskey
|
32e1b169da |
feat: consolidate and restructure the API reference (Phase 1) (#846)
* docs: correct HITL API integration flow and sync translations
- Fix the claim that the resume endpoint differs per app type (same
endpoint; only the entry endpoint differs)
- Tie workflow_run_id guidance to the human_input_required event
(chatflow message chunks don't carry it)
- Require the same user when resuming the event stream (mismatch
returns 404); add include_state_snapshot and continue_on_pause
guidance
- Note at the capture step that a null form_token means Email delivery
- Soften the upload-time validation claim to file size limits
- Split long paragraphs; align zh endpoint name with the reference page
* fix: correct API references against verified backend behavior
Audit of the Service API specs against dify hotfix/1.15.0-fix.1, with
every change code-verified and the serious items adversarially
confirmed. Applies to en/zh/ja.
- Add curl samples for GET endpoints with required query params
(Mintlify omits query params from generated snippets)
- Document 401 once in every spec's auth scheme description
- Correct wrong facts: workflow run detail returns inputs as a JSON
string; DELETE /conversations requires a JSON body; audio-to-text
accepts audio/{mp3,m4a,wav,amr,mpga} by MIME type; workflow log
created_by_account filters by email; triggered_from values are
app-run/webhook/schedule/plugin; stop endpoints' user semantics
differ per app type
- Remove unreachable docs: phantom text_replace SSE event, annotation
403, file preview endpoint in the workflow spec, invented
score_threshold bounds
- Make upload user optional (DEFAULT-USER fallback), fix upload
response example, add missing invalid_param error
- Declare text_to_speech.autoPlay in parameters responses (prose
values, no response-field enums)
* fix: complete API reference audit for knowledge and completion specs
* feat: add API spec consolidation pipeline
Phase-1 of the API docs consolidation: tooling that merges the five per-app-type Service API specs into one openapi_service.json per language, with every divergence resolved explicitly in resolutions.json and rendering-preserving namespacing for mode-scoped schema families. Includes the audit lint and parity checks (lint taught the new language-prefixed href scheme), hand-merged mode-aware SSE documentation for POST /chat-messages in en/zh/ja, and the New Agent (Beta) virtual nav group with code-verified mode notes.
* feat: consolidate API reference into one spec per language
Emit {en,zh,ja}/api-reference/openapi_service.json (82 ops, 130 components) from the audit-fixed per-app-type specs; wire docs.json to them with explicit per-app-type endpoint lists, x-mint.href URLs (/{lang}/api-reference/{tag}/{summary} with shared English slugs for in-place language switching), 265 redirects covering the legacy en and CJK URLs, per-app-type overview pages including New Agent (Beta), and rewritten legacy API links in 21 MDX bodies. The old five specs per language stay as pipeline input; they are no longer rendered.
* fix: remove dead conversation_completed error from chat specs
ConversationCompletedError is never raised anywhere at the verified 1.15.0 ref (7a4252b3de): controllers catch it, but no service code raises it, so the documented 400 conversation_completed can never fire. Remove the bullet and example from the chat and chatflow /chat-messages docs in en/zh/ja. Found and adversarially confirmed during the New Agent (PR #836) verification; filed on the upstream bug list.
* feat: add membership matrix and restructure nav config
* feat: rename resource tags and update all references
* feat: stamp per-operation availability lines
* feat: wire three-group API navigation
* feat: add app-type page coverage lint
* docs: rewrite chatflow overview as app-type API guide
* docs: polish chatflow overview zh and ja wording
* docs: rewrite workflow overview as app-type API guide
* docs: align workflow overview details across languages
* docs: expand new agent overview into app-type API guide
* docs: use task-oriented heading on new agent overview
* docs: rewrite chatbot and agent overview as app-type API guide
* docs: rewrite text generator overview as app-type API guide
* docs: match end user link text to merged spec summary
* docs: rewrite knowledge overview as app-type API guide
* docs: move knowledge api guide into api reference
* docs: localize ui labels on knowledge overview
* docs: refresh pipeline readme for restructure modes
* docs: name app-type pages in the guides sidebar
* feat: rename zh completion messages tag to match resource framing
* docs: prototype endpoints-first layout on chatflow overview
* docs: correct detail accuracy on chatflow overview
* docs: move human input flow guide into api reference
Move the shared HITL API integration walkthrough from its six per-product
copies into {en,zh,ja}/api-reference/guides/human-input-flow as the first
task guide in the API docs. Guides gains an App Types subgroup (expanded
by default) with the flow guide after it; six redirects cover the old
paths; the Human Input node docs and the chatflow overview link to the
new home.
* fix: update spec links to the moved human input guide
* fix: let spec lint accept mdx guide pages under api-reference
* docs: align chatflow zh and ja overviews to endpoints-first layout
* docs: polish chatflow zh and ja mode terms and hitl wording
* docs: align workflow overviews to endpoints-first layout
* docs: document form expiry path in human input flow guide
* docs: align new agent overviews to endpoints-first layout
* docs: align chatbot and agent overviews to endpoints-first layout
* docs: align text generator overviews to endpoints-first layout
* docs: align knowledge overviews to endpoints-first layout
* docs: correct built-in metadata examples and agent heading
* docs: flatten app-type pages directly under guides
* docs: make guide pages self-contained and trim reference detail
* docs: add get started guide and retire developing-with-apis
* docs: update new agent api behavior for latest main
New Agent behavior re-verified against dify origin/main (f3ba2846):
agent_thought events now stream through the Service API carrying the
model's reasoning steps and tool calls; a new agent_not_published 400
fires on Send Chat Message and Get App Parameters; the files claim is
softened to contents-not-processed (raw references now reach the prompt;
runtime confirmation pending). Streaming-only, message_end metadata, and
the endpoint surface are unchanged.
* docs: audit fixes for get started and human input flow guides
* docs: fix em dash spacing and ja sentence length in get started
* docs: move message_end note to the send endpoint line
* docs: update writing guides and API skill for app-type naming
- Glossary and zh/ja translation guides: Workflow and Chatflow app types stay English (Workflow 应用 / Chatflow アプリ); lowercase workflow localizes to 工作流 / ワークフロー.
- formatting-guide: API reference links use the language prefix with English slugs.
- dify-docs-api-reference skill: Spec Structure documents source specs merged into openapi_service.json by the pipeline.
* feat: add operation sidebar titles and simplify API redirects
- merge_specs stamps x-mint.metadata.sidebarTitle per operation so translated summaries show in the sidebar.
- Redirects reduced to a catch-all to the English API home plus three knowledge-base exceptions.
- memberships, strings, and SSE overrides carry app-type labels (Workflow/Chatflow English, New Agent, API Overviews group).
* docs: correct app-type naming and translations across API specs
- English mode enum labels Chatflow and Workflow apps.
- zh/ja app references use Workflow/Chatflow; New Agent is 新 Agent / 新しい Agent.
- ja knowledge tag データセット becomes ナレッジベース; zh 模型提供商 becomes 模型供应商.
- Regenerate merged openapi_service.json with per-operation sidebar titles.
* docs: add streaming, errors, and end-user identity API guides
- Consume Streaming Responses: response modes, SSE parsing, event dispatch, and reconnect.
- Handle Errors and Rate Limits: the error envelope, status classes, and retry guidance.
- End User Identity: what the user field scopes and why it stays consistent.
- English source with zh and ja translations.
* docs: reconcile API guides and apply app-type naming
- Reader-test fixes and content audit on get-started and the app-type overview pages.
- zh/ja reconciled to the English source.
- Workflow/Chatflow and New Agent naming applied in prose.
* feat: wire API nav and redirects for consolidated guides
- Rename the guides group to API Overviews and register the new guide pages.
- Redirects: catch-all to the English API home plus three product-embedded knowledge-base links to the Knowledge guide.
* fix: normalize zh model-provider term to 模型供应商
Aligns the POSITION_PROVIDER_* descriptions with the canonical glossary term.
* docs: use Info callouts for guide forward-link notes
Wrap the authentication, base URL, and `user` field forward-reference in each app-type guide (agent, chat, chatflow, completion, workflow; en/zh/ja) in an `<Info>` callout.
* refactor: remove one-time analyze mode and verification compose
- Drop the `analyze` mode (design-time spec-overlap analysis) and its helpers; the merge is stable and nothing invokes it.
- Delete `compose.swagger.yml`, the throwaway local code-vs-spec verification stack (flagged in review for inline credentials).
- README: drop the analyze entry and correct the redirect description.
* fix: correct Chatflow naming and reasoning wording in SSE overrides
- Use "Chatflow" (English) for the app type in the `/chat-messages` SSE tables instead of 对话流/チャットフロー, and fix the legacy zh chatflow "对话流工作流" description. Standalone table cells were missed by the earlier app-type rename.
- Describe `reasoning_chunk` as "reasoning content" in en/ja (matching the `reasoning` field and the zh wording) instead of "chain-of-thought".
* docs: refine API guide wording and simplify the human-input example
* docs: standardize Workflow and Chatflow app-type capitalization
Capitalize Chatflow and Workflow when they name an app type; keep "workflow" lowercase for the general engine, graph, or run sense.
* fix: use 供应商 for model provider in the zh Knowledge spec
* fix: rename the Knowledge API nav group to "Knowledge APIs"
* fix: un-deprecate Update Document by Text in the Knowledge spec
* translate: un-deprecate Update Document by Text in zh/ja specs
Mirror the en fix (
|