Skip to content

Commit 16514da

Browse files
comfy-pr-botcomfy-pr-bot
authored
chore(openapi): sync shared API contract from cloud@d10ff72 (Comfy-Org#14518)
1 parent 8483c21 commit 16514da

1 file changed

Lines changed: 187 additions & 8 deletions

File tree

‎openapi.yaml‎

Lines changed: 187 additions & 8 deletions
Original file line numberDiff line numberDiff line change
@@ -673,6 +673,35 @@ components:
673673
- created_at
674674
- updated_at
675675
type: object
676+
JobsCancelRequest:
677+
additionalProperties: false
678+
description: Request to cancel multiple jobs by ID.
679+
properties:
680+
job_ids:
681+
description: Job identifiers (UUIDs) to cancel.
682+
items:
683+
format: uuid
684+
type: string
685+
maxItems: 100
686+
minItems: 1
687+
type: array
688+
required:
689+
- job_ids
690+
type: object
691+
JobsCancelResponse:
692+
description: Response for POST /api/jobs/cancel.
693+
properties:
694+
cancelled:
695+
description: |
696+
Job IDs for which a cancel event was successfully dispatched by this
697+
call. Jobs already in a terminal or cancelling state are idempotently
698+
skipped and will not appear here.
699+
items:
700+
type: string
701+
type: array
702+
required:
703+
- cancelled
704+
type: object
676705
JobsListResponse:
677706
description: Paginated list of jobs for the authenticated user.
678707
properties:
@@ -1006,7 +1035,7 @@ components:
10061035
description: If true, clear all pending jobs from the queue
10071036
type: boolean
10081037
delete:
1009-
description: Array of PENDING job IDs to cancel
1038+
description: Array of job IDs to cancel; pending and running jobs transition to cancelled
10101039
items:
10111040
type: string
10121041
type: array
@@ -1822,6 +1851,83 @@ paths:
18221851
summary: Update asset metadata
18231852
tags:
18241853
- file
1854+
/api/assets/{id}/content:
1855+
get:
1856+
description: |
1857+
Returns the binary content of an asset by ID.
1858+
1859+
The contract is the same across runtimes — "GET this path and you
1860+
receive the asset's bytes" — but the mechanism differs:
1861+
- **Local ComfyUI** streams the bytes directly (`200`,
1862+
`application/octet-stream`).
1863+
- **Cloud** does not proxy large files; it responds `302` with a
1864+
`Location` redirect to a short-lived signed storage URL. Clients that
1865+
follow redirects (browsers, `fetch`/XHR, `<img>`/`<video>`) receive
1866+
the bytes transparently.
1867+
1868+
Prefer this over the filename-addressed `/api/view` when you have an
1869+
asset ID.
1870+
operationId: getAssetContent
1871+
parameters:
1872+
- description: Asset ID
1873+
in: path
1874+
name: id
1875+
required: true
1876+
schema:
1877+
type: string
1878+
- description: |
1879+
Content-Disposition for the response: `attachment` (download) or
1880+
`inline` (render in browser). Defaults to `attachment`.
1881+
in: query
1882+
name: disposition
1883+
schema:
1884+
default: attachment
1885+
enum:
1886+
- inline
1887+
- attachment
1888+
type: string
1889+
responses:
1890+
"200":
1891+
content:
1892+
application/octet-stream:
1893+
schema:
1894+
format: binary
1895+
type: string
1896+
description: Asset content stream (local runtime streams the bytes directly)
1897+
"302":
1898+
description: Redirect to a signed storage URL (cloud runtime)
1899+
headers:
1900+
Cache-Control:
1901+
description: Private caching directive scoped to the signed URL lifetime
1902+
schema:
1903+
type: string
1904+
Location:
1905+
description: Short-lived signed URL to the asset content in storage
1906+
schema:
1907+
type: string
1908+
Vary:
1909+
description: Partitions any cached redirect by auth credentials so a private redirect is not reused across users
1910+
schema:
1911+
type: string
1912+
"404":
1913+
content:
1914+
application/json:
1915+
schema:
1916+
$ref: '#/components/schemas/ErrorResponse'
1917+
description: Asset not found
1918+
"500":
1919+
content:
1920+
application/json:
1921+
schema:
1922+
$ref: '#/components/schemas/ErrorResponse'
1923+
description: Internal server error
1924+
security:
1925+
- ApiKeyAuth: []
1926+
- BearerAuth: []
1927+
- CookieAuth: []
1928+
summary: Get asset content
1929+
tags:
1930+
- file
18251931
/api/assets/{id}/tags:
18261932
delete:
18271933
description: Removes one or more tags from an existing asset
@@ -2675,14 +2781,20 @@ paths:
26752781
summary: Get internationalisation translation strings
26762782
/api/interrupt:
26772783
post:
2784+
deprecated: true
26782785
description: |
2679-
Cancel all currently RUNNING jobs for the authenticated user.
2680-
This will interrupt any job that is currently in 'in_progress' status.
2681-
Note: This endpoint only affects running jobs. To cancel pending jobs, use /api/queue.
2786+
Deprecated. Prefer the jobs-namespace cancel endpoints:
2787+
POST /api/jobs/{job_id}/cancel for a single job, or
2788+
POST /api/jobs/cancel to cancel jobs by ID.
2789+
2790+
Cancels the first active job for the authenticated user (the currently
2791+
running job if there is one, otherwise the next pending job). Takes no
2792+
body and cannot target a specific job — use the jobs-namespace endpoints
2793+
for that.
26822794
operationId: interruptJob
26832795
responses:
26842796
"200":
2685-
description: Success - Job interrupted or no running job found
2797+
description: Success - first active job cancelled, or no active job found
26862798
"401":
26872799
content:
26882800
application/json:
@@ -2695,7 +2807,7 @@ paths:
26952807
schema:
26962808
$ref: '#/components/schemas/ErrorResponse'
26972809
description: Internal server error
2698-
summary: Interrupt currently running jobs
2810+
summary: Interrupt the first active job
26992811
tags:
27002812
- queue
27012813
/api/job/{job_id}/status:
@@ -2954,6 +3066,64 @@ paths:
29543066
summary: Cancel a job
29553067
tags:
29563068
- workflow
3069+
/api/jobs/cancel:
3070+
post:
3071+
description: |
3072+
Cancel one or more jobs for the authenticated user in a single request.
3073+
3074+
State-agnostic: cancels both pending and running jobs (both transition to
3075+
the cancelled state via the same mechanism as the single-job endpoint).
3076+
3077+
Idempotent per job: a job already in a terminal or cancelling state is a
3078+
no-op and simply will not appear in the returned `cancelled` list.
3079+
3080+
Fail-fast on unknown IDs: if any provided job ID does not exist for this
3081+
user, the request returns 404 and no jobs are cancelled. This surfaces
3082+
bad IDs to the caller rather than silently dropping them.
3083+
3084+
This is the canonical batch-cancel endpoint. The delete operation on
3085+
POST /api/queue is deprecated in favour of this.
3086+
operationId: cancelJobs
3087+
requestBody:
3088+
content:
3089+
application/json:
3090+
schema:
3091+
$ref: '#/components/schemas/JobsCancelRequest'
3092+
required: true
3093+
responses:
3094+
"200":
3095+
content:
3096+
application/json:
3097+
schema:
3098+
$ref: '#/components/schemas/JobsCancelResponse'
3099+
description: Success - cancel requests dispatched (or jobs were already terminal)
3100+
"400":
3101+
content:
3102+
application/json:
3103+
schema:
3104+
$ref: '#/components/schemas/ErrorResponse'
3105+
description: Bad Request - job_ids is missing, empty, exceeds the maximum count, or contains an invalid UUID
3106+
"401":
3107+
content:
3108+
application/json:
3109+
schema:
3110+
$ref: '#/components/schemas/ErrorResponse'
3111+
description: Unauthorized - Authentication required
3112+
"404":
3113+
content:
3114+
application/json:
3115+
schema:
3116+
$ref: '#/components/schemas/ErrorResponse'
3117+
description: One or more job IDs not found for this user (no jobs cancelled)
3118+
"500":
3119+
content:
3120+
application/json:
3121+
schema:
3122+
$ref: '#/components/schemas/ErrorResponse'
3123+
description: Internal server error - cancellation failed
3124+
summary: Cancel multiple jobs
3125+
tags:
3126+
- workflow
29573127
/api/node_replacements:
29583128
get:
29593129
description: |
@@ -3104,9 +3274,18 @@ paths:
31043274
tags:
31053275
- queue
31063276
post:
3277+
deprecated: true
31073278
description: |
3108-
Cancel specific PENDING jobs by ID or clear all pending jobs in the queue.
3109-
Note: This endpoint only affects pending jobs. To cancel running jobs, use /api/interrupt.
3279+
Deprecated. Prefer the jobs-namespace cancel endpoints:
3280+
POST /api/jobs/cancel for cancelling jobs by ID, and
3281+
POST /api/jobs/{job_id}/cancel for a single job.
3282+
3283+
Cancel specific jobs by ID (the `delete` field) or clear all pending
3284+
jobs in the queue (the `clear` field). Despite the `delete` naming, this
3285+
does not delete anything — listed jobs transition to the cancelled state,
3286+
and `delete` cancels both pending and running jobs (not pending-only as
3287+
previously documented). Job-by-ID cancellation is superseded by
3288+
POST /api/jobs/cancel; `clear` has no jobs-namespace replacement yet.
31103289
operationId: manageQueue
31113290
requestBody:
31123291
content:

0 commit comments

Comments
 (0)