Add Cloud API documentation with examples and OpenAPI spec #701
Conversation
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
- Add api-reference.mdx with code examples (curl, TypeScript, Python) - Add overview.mdx explaining authentication, core concepts, workflows - Add openapi.mdx integrating OpenAPI specification - Add openapi-cloud.yaml with full API spec (workflows, assets, jobs, WebSocket) - Update navigation to include new Cloud API section Fixes from review: - Use correct hash format (blake3:<64 hex chars>) in examples - Fix Python WebSocket async iteration bug - Use Node.js fs/promises instead of Deno APIs - Align on 'Experimental API' terminology across all files - Document hash format differences between endpoints
- Create zh-CN/development/cloud/overview.mdx - Create zh-CN/development/cloud/api-reference.mdx - Create zh-CN/development/cloud/openapi.mdx - Update zh-CN/development/overview.mdx with Cloud API link - Update zh-CN/get_started/cloud.mdx with Cloud API card - Update zh-CN/index.mdx with Cloud API card in development section - Fix branding: use 'Comfy Cloud' consistently (not 'ComfyUI Cloud')
- Fix branding in openapi-cloud.yaml: 'ComfyUI Cloud' → 'Comfy Cloud' - Fix zh-CN/development/cloud/openapi.mdx: revert /zh-CN/api-reference/cloud to /api-reference/cloud (OpenAPI reference is not localized) - Fix zh-CN/development/cloud/overview.mdx: update anchor links to match Chinese headings
Link Validation Failed❌ zh-CN/development/cloud/openapi.mdx
|
The interactive API reference cards linked to auto-generated OpenAPI paths that the link checker cannot verify. Removed these sections from both English and Chinese openapi.mdx files.
This reverts commit bdb505c.
- Create api-reference/cloud/overview.mdx as landing page - Update links in openapi.mdx files to point to /api-reference/cloud/overview
Link Validation Failed❌ zh-CN/development/cloud/openapi.mdx
|
Link Validation Failed❌ zh-CN/development/cloud/openapi.mdx
|
- Fix link in zh-CN/development/cloud/openapi.mdx to point to Chinese API reference - Add missing zh-CN/registry/claim-my-node to Chinese navigation
Document how to pass api_key_comfy_org in extra_data when workflows contain Partner Nodes (Flux Pro, Ideogram, etc.). Added to both English and Chinese API reference docs.
robinjhuang
approved these changes
Jan 5, 2026
- Changed endpoint from /api/job/{id}/status to /api/jobs/{id}
- Use top-level 'status' field (not execution_status.status_str)
- Check for 'completed' status (not 'success')
…lues
- /api/jobs/{id} returns user-friendly status (pending, in_progress, completed, etc.)
- /api/job/{id}/status returns raw internal states (success, executing, etc.)
- Added note recommending /api/jobs/{id} for polling
- Remove Reference Well-Known Assets section (from-hash API not usable as documented - hash format mismatch between upload and from-hash) - Add note about subfolder being ignored in Upload Mask (cloud uses flat content-addressed storage) - Fix downloadOutputs in End-to-End example to use redirect:manual to avoid sending auth headers to GCS signed URLs Testing confirmed: - Partner nodes with extra_data work correctly - Cancel job and interrupt execution work - Upload mask works (subfolder ignored) - from-hash endpoint exists but requires blake3: format hashes that aren't returned by any upload API
Tested WebSocket real-time updates - all message types work correctly: - status, notification, execution_start, executing, progress, progress_state, executed, execution_success - Binary preview images received during sampling Added missing 'notification' message type which provides user-friendly status messages like 'Executing workflow...' and 'Done!'
…ward compatibility
huntcsg
force-pushed
the
document-cloud-comfy-apis
branch
from
d7ded99 to
a30c063
Compare
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.
Fixes from review: