docs: add Comfy API v2 reference

[wei-hai]

What changed

• Add a generated Comfy API v2 OpenAPI document for Mintlify.
• Add a dedicated Comfy API v2 Reference tab for English, Chinese, Japanese, and Korean documentation.

Why

The versioned v2 HTTP API now has a public, generated reference alongside the existing Cloud API reference.

Validation

• OpenAPI parsing and Mintlify OpenAPI validation passed.
• Generated artifact matches the public projection.
• No known internal markers or private references remain.
• Full preview rendered the generated navigation and endpoint pages without console or overlay errors.

The OpenAPI file is generated by the upstream public-spec workflow and should not be edited by hand.

[coderabbitai]

No actionable comments were generated in the recent review. 🎉

ℹ️ Recent review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: f0b0e90a-ff56-405c-9ce6-b6f5d70b49aa

📥 Commits

Reviewing files that changed from the base of the PR and between 25e2d84 and b98306b.

📒 Files selected for processing (1)

• docs.json

---

📝 Walkthrough

Walkthrough

Added a generated Comfy API v2 OpenAPI 3.0.3 contract covering asset and job APIs, then exposed it through English, Chinese, Japanese, and Korean documentation navigation.

Changes

Comfy API v2 reference

Layer / File(s)	Summary
API v2 contract openapi-v2.yaml	Defines authenticated asset uploads, hash deduplication, downloads, workflow jobs, polling, SSE events, cancellation, errors, security, and reusable schemas.
Localized reference navigation docs.json	Adds API v2 OpenAPI navigation entries for English, Chinese, Japanese, and Korean documentation tabs.

Suggested reviewers: lin-bot23, comfyui-wiki

🚥 Pre-merge checks | ✅ 2

✅ Passed checks (2 passed)

Check name	Status	Explanation
Linked Issues check	✅ Passed	Check skipped because no linked issues were found for this pull request.
Out of Scope Changes check	✅ Passed	Check skipped because no linked issues were found for this pull request.

✨ Finishing Touches

🧪 Generate unit tests (beta)

• Create PR with unit tests
• Commit unit tests in branch agent/v2-api-reference

✨ Simplify code

• Create PR with simplified code
• Commit simplified code in branch agent/v2-api-reference

---

Thanks for using CodeRabbit! It's free for OSS, and your support helps us grow. If you like it, consider giving us a shout-out.

❤️ Share

• X
• Mastodon
• Reddit
• LinkedIn

_{Comment @coderabbitai help to get the list of available commands.}

[mintlify]

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

Project	Status	Preview	Updated (UTC)
comfy	🟢 Ready	View Preview	Jul 31, 2026, 12:19 AM

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

[coderabbitai]

Actionable comments posted: 4

🤖 Prompt for all review comments with AI agents

Verify each finding against current code. Fix only still-valid issues, skip the
rest with a brief reason, keep changes minimal, and validate.

Inline comments:
In `@openapi-v2.yaml`:
- Around line 88-92: Add the same explicit maxItems bound to the tags arrays in
the multipart upload schema at openapi-v2.yaml lines 88-92 and the from-hash
request body at lines 164-167. Optionally constrain each tag string with
maxLength, but ensure both canonical contract definitions declare the shared
tag-count limit.
- Around line 22-24: The global security declaration in openapi-v2.yaml
currently allows unauthenticated access through the {} fallback; update the
canonical contract so Cloud/serverless operations require bearerAuth, while
preserving anonymous access only for the intended self-hosted surface or
explicitly anonymous operations. Remove the global optional-auth alternative and
express any permitted anonymous access at the appropriate surface or operation
level.
- Around line 110-118: Remove the Retry-After header reference from the 409
hash_mismatch response while preserving its description and ErrorEnvelope
content schema; keep Retry-After defined only for applicable rate-limit
responses.
- Around line 714-726: Update the progress and error schema properties in the
job response to represent nullability with an OpenAPI 3.0-compatible anyOf/oneOf
union containing the referenced Progress or JobError schema plus a null branch.
Remove the sibling nullable: true values while preserving the existing
descriptions and references.

🪄 Autofix (Beta)

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

---

ℹ️ Review info

⚙️ Run configuration

Configuration used: Organization UI

Review profile: ASSERTIVE

Plan: Pro Plus

Run ID: 3119bf9d-13b0-404b-ab6e-22f5096abc0f

📥 Commits

Reviewing files that changed from the base of the PR and between ca5c731 and 25e2d84.

📒 Files selected for processing (2)

• docs.json
• openapi-v2.yaml

[robinjhuang]

@wei-hai Can we add this under "Development"? The previous references APIs are at the top level nav bar, but I don't think they should actually be there. I want to change that soon.

[wei-hai]

@robinjhuang Done in b98306b. I moved the Comfy API v2 reference under Development → ComfyUI APIs in all four locales and removed its top-level tabs. I left the existing Registry and Cloud API reference tabs untouched for your follow-up cleanup. Mintlify validation passes with the nested navigation.