Skip to content

chore: sync vendored Comfy API v2 spec (cloud@04133db) #40

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Open
comfy-pr-bot wants to merge 1 commit into
base: main
Choose a base branch
from
+28 −16
Open

chore: sync vendored Comfy API v2 spec (cloud@04133db) #40

Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
44 changes: 28 additions & 16 deletions spec/openapi.yaml
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -1,9 +1,8 @@
# Comfy API v2 — public spec, vendored into this SDK.
# Comfy API v2 — public specification.
#
# GENERATED / VENDORED ONE-WAY — DO NOT HAND-EDIT.
# GENERATED ONE-WAY — DO NOT HAND-EDIT.
# Projected automatically from the canonical Comfy API v2 contract and
# synced in by CI. Change the upstream contract, not this copy: the SDK's
# own CI regenerates its low layer from this file and FAILS ON DRIFT.
# synced by CI. Change the upstream contract, not this public copy.

openapi: 3.0.3
info:
Expand All @@ -15,11 +14,12 @@ servers:
description: Self-hosted (comfy-api-proxy)
- url: https://cloud.comfy.org
description: Comfy Cloud
- url: https://{deployment}.comfy.org
description: Serverless deployment (URL shape not final)
- url: https://{deployment}.run.comfy.app
description: Serverless deployment
variables:
deployment:
default: my-deployment
description: DNS-safe deployment id (subdomain label). Staging uses {deployment}.stg.run.comfy.app.
default: dep-1234abcd-56ef-7890-abcd-ef1234567890
security:
- bearerAuth: []
- {}
Expand Down Expand Up @@ -394,7 +394,7 @@ paths:
schema:
$ref: '#/components/schemas/ErrorEnvelope'
'429':
description: '`queue_full` — bounded queue depth reached.'
description: '`queue_full` (bounded queue depth reached) or, on deployment-scoped surfaces, `deployment_not_ready` (deployment still provisioning/starting). Disambiguate by `error.code`; both mean back off and retry after `Retry-After`.'
headers:
Retry-After:
$ref: '#/components/headers/RetryAfter'
Expand Down Expand Up @@ -573,14 +573,14 @@ components:
required: true
schema:
type: string
example: job_01JZTGXW9Q2M4R8V0B1N3P5D7F
example: 7f3d2c1b-9a8e-4d6f-b012-3c4d5e6f7a8b
AssetId:
name: id
in: path
required: true
schema:
type: string
example: asset_01JZV8Q3M7K2W9X0Y1Z2A3B4C5
example: 9f8a1c0d-2b3e-4f56-8a7b-1c2d3e4f5a6b
BlakeHash:
name: hash
in: path
Expand Down Expand Up @@ -643,7 +643,7 @@ components:
properties:
id:
type: string
example: asset_01JZV8Q3M7K2W9X0Y1Z2A3B4C5
example: 9f8a1c0d-2b3e-4f56-8a7b-1c2d3e4f5a6b
hash:
type: string
nullable: true
Expand Down Expand Up @@ -691,7 +691,7 @@ components:
properties:
id:
type: string
example: job_01JZTGXW9Q2M4R8V0B1N3P5D7F
example: 7f3d2c1b-9a8e-4d6f-b012-3c4d5e6f7a8b
status:
$ref: '#/components/schemas/JobStatus'
created_at:
Expand Down Expand Up @@ -755,7 +755,7 @@ components:
'
JobUrls:
type: object
description: Embedded follow-up links — follow these, don't build URLs.
description: Embedded follow-up links — follow these, don't build URLs. A link is either an absolute URL or a host-relative reference (leading `/`) that already includes any prefix the serving surface is mounted under (e.g. a serverless gateway's `/deployment/{deployment_id}/api/v2`). Clients MUST resolve a host-relative link against the request origin (scheme + authority), never against a configured base URL — joining it to a base URL that carries the same mount prefix duplicates the prefix.
required:
- self
- events
Expand Down Expand Up @@ -843,7 +843,7 @@ components:
id:
type: string
description: Asset UUID.
example: asset_01JZV9R4N8...
example: 9f8a1c0d-2b3e-4f56-...

@coderabbitai coderabbitai Bot Aug 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Use a complete UUID for Output.id.example.

The value contains ... and is not a valid UUID, although Output.id is documented as an asset UUID. OpenAPI tooling or generated test data can reject this example.

Proposed correction 
-          example: 9f8a1c0d-2b3e-4f56-...
+          example: 9f8a1c0d-2b3e-4f56-8a7b-1c2d3e4f5a6b
📝 Committable suggestion

‼️ IMPORTANT
Carefully review the code before committing. Ensure that it accurately replaces the highlighted code, contains no missing lines, and has no issues with indentation. Thoroughly test & benchmark the code to ensure it meets the requirements.

Suggested change
example: 9f8a1c0d-2b3e-4f56-...
example: 9f8a1c0d-2b3e-4f56-8a7b-1c2d3e4f5a6b
🤖 Prompt for 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.

In `@spec/openapi.yaml` at line 846, Replace the truncated example under Output.id
with a complete, valid UUID string, preserving its role as the documented asset
UUID example.

hash:
type: string
nullable: true
Expand Down Expand Up @@ -899,6 +899,18 @@ components:

`not_found` (404), `unauthorized` (401), `forbidden` (403).

Deployment-scoped surfaces add: `deployment_not_ready` (429 +

Retry-After — the deployment can still reach ready; retry) and

`deployment_stopped` (422 — terminal deployment state; a retry

cannot succeed without operator action). A 429 is disambiguated

by `error.code` alone; clients should treat any 429 + Retry-After

as "back off and retry".

Comment on lines +902 to +913

@coderabbitai coderabbitai Bot Aug 7, 2026

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

🗄️ Data Integrity & Integration | 🟡 Minor | ⚡ Quick win

Add deployment_stopped to the operation-level 422 contract.

ErrorEnvelope now documents deployment_stopped as a deployment-scoped 422, but the POST /api/v2/jobs response at Line 391 still lists only invalid_workflow, workflow_format_ui, missing_asset, and idempotency_key_reuse. The operation documentation is incomplete for deployment-scoped servers.

Add deployment_stopped to that 422 response description or define a deployment-specific 422 response.

🤖 Prompt for 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.

In `@spec/openapi.yaml` around lines 902 - 913, Add deployment_stopped to the POST
/api/v2/jobs operation-level 422 response contract, alongside invalid_workflow,
workflow_format_ui, missing_asset, and idempotency_key_reuse, or reference a
deployment-specific 422 response. Keep the existing error codes and response
behavior unchanged.

'
required:
- error
Expand Down Expand Up @@ -964,7 +976,7 @@ components:
type: string
AssetReference:
type: object
description: "The typed asset-reference object placed inside workflow JSON where a\nfilename would normally go (documented here for tooling; it is not a\nrequest/response body itself):\n\n {\"__type\": \"core/ASSET\",\n \"info\": {\"id\": \"asset_...\", \"hash\": \"blake3:...\",\n \"file_path\": \"photo.png\"}}\n\n`info.id` (the asset UUID) is required in v1 and authoritative;\n`hash` and `file_path` are optional staging/lookup hints and never\noverride a present `id`. A malformed reference or one that is not\nresolvable/owned by the caller fails submission with 422\n`missing_asset`.\n"
description: "The typed asset-reference object placed inside workflow JSON where a\nfilename would normally go (documented here for tooling; it is not a\nrequest/response body itself):\n\n {\"__type\": \"core/ASSET\",\n \"info\": {\"id\": \"<asset-uuid>\", \"hash\": \"blake3:...\",\n \"file_path\": \"photo.png\"}}\n\n`info.id` (the asset UUID) is required in v1 and authoritative;\n`hash` and `file_path` are optional staging/lookup hints and never\noverride a present `id`. A malformed reference or one that is not\nresolvable/owned by the caller fails submission with 422\n`missing_asset`.\n"
required:
- __type
- info
Expand All @@ -980,7 +992,7 @@ components:
properties:
id:
type: string
example: asset_01JZV8Q3M7K2W9X0Y1Z2A3B4C5
example: 9f8a1c0d-2b3e-4f56-8a7b-1c2d3e4f5a6b
hash:
type: string
example: blake3:9f8a1c0d...
Expand Down
Loading