From fd17b95e1c94777176ac0bada64a5275663f1769 Mon Sep 17 00:00:00 2001 From: Cursor Agent Date: Thu, 7 May 2026 18:10:11 +0000 Subject: [PATCH 1/2] Mark deprecated cloud-runtime endpoints in openapi.yaml MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add five cloud-runtime FE-facing endpoints to the OSS spec with deprecated: true and standardized description prefixes: - GET /api/history_v2 — superseded by GET /api/jobs - GET /api/history_v2/{prompt_id} — superseded by GET /api/jobs/{prompt_id} - GET /api/logs — returns static placeholder; no real log data - GET /api/viewvideo — alias of GET /api/view for legacy video playback - GET /api/job/{job_id}/status — superseded by GET /api/jobs/{job_id} Each endpoint is tagged x-runtime: [cloud] and follows the same deprecation convention established for /api/history endpoints. Co-authored-by: Matt Miller --- openapi.yaml | 189 +++++++++++++++++++++++++++++++++++++++++++++++++++ 1 file changed, 189 insertions(+) diff --git a/openapi.yaml b/openapi.yaml index 4216c1a6c..5d8f56c3d 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -349,6 +349,35 @@ paths: "404": description: Job not found + /api/job/{job_id}/status: + get: + operationId: getJobStatus + tags: [queue] + summary: Get job status (legacy singular path) + x-runtime: [cloud] + deprecated: true + description: | + **Deprecated.** This endpoint is superseded by `GET /api/jobs/{job_id}`. + Clients should migrate; the endpoint is retained for backward + compatibility but will be removed in a future release. + parameters: + - name: job_id + in: path + description: The job ID to fetch status for. + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Job status + content: + application/json: + schema: + $ref: "#/components/schemas/JobDetailResponse" + "404": + description: Job not found + # --------------------------------------------------------------------------- # History # --------------------------------------------------------------------------- @@ -436,6 +465,75 @@ paths: additionalProperties: $ref: "#/components/schemas/HistoryEntry" + /api/history_v2: + get: + operationId: getHistoryV2 + tags: [history] + summary: Get execution history (v2 format) + x-runtime: [cloud] + deprecated: true + description: | + **Deprecated.** This endpoint is superseded by `GET /api/jobs`. + Clients should migrate; the endpoint is retained for backward + compatibility but will be removed in a future release. + parameters: + - $ref: "#/components/parameters/ComfyUserHeader" + - name: limit + in: query + schema: + type: integer + description: Maximum number of history entries to return + - name: offset + in: query + schema: + type: integer + default: 0 + description: Pagination offset + responses: + "200": + description: History entries + content: + application/json: + schema: + type: object + properties: + items: + type: array + items: + $ref: "#/components/schemas/HistoryEntry" + pagination: + $ref: "#/components/schemas/PaginationInfo" + + /api/history_v2/{prompt_id}: + get: + operationId: getHistoryV2ByPromptId + tags: [history] + summary: Get v2 history for a specific prompt + x-runtime: [cloud] + deprecated: true + description: | + **Deprecated.** This endpoint is superseded by `GET /api/jobs/{prompt_id}`. + Clients should migrate; the endpoint is retained for backward + compatibility but will be removed in a future release. + parameters: + - $ref: "#/components/parameters/ComfyUserHeader" + - name: prompt_id + in: path + description: The prompt ID to fetch history for. + required: true + schema: + type: string + format: uuid + responses: + "200": + description: Single history entry + content: + application/json: + schema: + $ref: "#/components/schemas/HistoryEntry" + "404": + description: Prompt not found + # --------------------------------------------------------------------------- # Upload # --------------------------------------------------------------------------- @@ -592,6 +690,71 @@ paths: "404": description: File not found + /api/viewvideo: + get: + operationId: viewVideo + tags: [view] + summary: View or download a video file (legacy alias) + x-runtime: [cloud] + deprecated: true + description: | + **Deprecated.** This endpoint is an alias of `GET /api/view` added for + legacy history-queue video playback. Callers should use `/api/view` + directly; the endpoint is retained for backward compatibility but will + be removed in a future release. + parameters: + - name: filename + in: query + required: true + schema: + type: string + description: Name of the file to view + - name: type + in: query + schema: + type: string + enum: [input, output, temp] + default: output + description: Directory type + - name: subfolder + in: query + schema: + type: string + description: Subfolder within the directory + - name: preview + in: query + schema: + type: string + description: Preview format hint (e.g. "webp;90") + - name: channel + in: query + schema: + type: string + enum: [rgba, rgb, a] + description: Channel extraction mode + responses: + "200": + description: File content + content: + image/*: + schema: + type: string + format: binary + video/*: + schema: + type: string + format: binary + audio/*: + schema: + type: string + format: binary + application/octet-stream: + schema: + type: string + format: binary + "404": + description: File not found + /api/view_metadata/{folder_name}: get: operationId: viewMetadata @@ -692,6 +855,32 @@ paths: x-runtime: [cloud] description: "[cloud-only] How the templates version was resolved. Local ComfyUI returns null." + /api/logs: + get: + operationId: getLogs + tags: [system] + summary: Get server logs (placeholder) + x-runtime: [cloud] + deprecated: true + description: | + **Deprecated.** This endpoint returns a static placeholder response and + provides no real log data. It is retained only to avoid breaking clients + that still call it. Clients should remove their dependency; the endpoint + will be removed in a future release. + responses: + "200": + description: Static placeholder log response + content: + application/json: + schema: + type: object + properties: + logs: + type: array + items: + type: string + description: Log lines (always empty in current implementation) + # --------------------------------------------------------------------------- # Node / Object Info # --------------------------------------------------------------------------- From 81af8e4de271f76a559c8d1c76598e93f841cf3a Mon Sep 17 00:00:00 2001 From: Matt Miller Date: Fri, 8 May 2026 18:30:11 -0700 Subject: [PATCH 2/2] fix(spec): consolidate duplicate path entries on deprecated cloud-runtime endpoints Previous commit added new path entries with `deprecated: true` for `/api/job/{job_id}/status`, `/api/history_v2`, `/api/history_v2/{prompt_id}`, `/api/logs`, and `/api/viewvideo`, but the canonical entries already existed elsewhere in the file. Result: 5 duplicate path keys (Spectral parser errors), and the deprecation flag did not land on the operations that FE clients consume by operationId. This commit moves `deprecated: true` plus the standardized "Deprecated." description onto the canonical operations (`getCloudJobStatus`, `getHistoryV2`, `getHistoryV2ByPromptId`, `getCloudLogs`, `viewVideo`) and removes the duplicate entries. Operation IDs and response schemas are unchanged. Spectral lint passes with zero new warnings. --- openapi.yaml | 224 +++++++-------------------------------------------- 1 file changed, 27 insertions(+), 197 deletions(-) diff --git a/openapi.yaml b/openapi.yaml index 5d8f56c3d..c9ae3dab5 100644 --- a/openapi.yaml +++ b/openapi.yaml @@ -349,35 +349,6 @@ paths: "404": description: Job not found - /api/job/{job_id}/status: - get: - operationId: getJobStatus - tags: [queue] - summary: Get job status (legacy singular path) - x-runtime: [cloud] - deprecated: true - description: | - **Deprecated.** This endpoint is superseded by `GET /api/jobs/{job_id}`. - Clients should migrate; the endpoint is retained for backward - compatibility but will be removed in a future release. - parameters: - - name: job_id - in: path - description: The job ID to fetch status for. - required: true - schema: - type: string - format: uuid - responses: - "200": - description: Job status - content: - application/json: - schema: - $ref: "#/components/schemas/JobDetailResponse" - "404": - description: Job not found - # --------------------------------------------------------------------------- # History # --------------------------------------------------------------------------- @@ -465,75 +436,6 @@ paths: additionalProperties: $ref: "#/components/schemas/HistoryEntry" - /api/history_v2: - get: - operationId: getHistoryV2 - tags: [history] - summary: Get execution history (v2 format) - x-runtime: [cloud] - deprecated: true - description: | - **Deprecated.** This endpoint is superseded by `GET /api/jobs`. - Clients should migrate; the endpoint is retained for backward - compatibility but will be removed in a future release. - parameters: - - $ref: "#/components/parameters/ComfyUserHeader" - - name: limit - in: query - schema: - type: integer - description: Maximum number of history entries to return - - name: offset - in: query - schema: - type: integer - default: 0 - description: Pagination offset - responses: - "200": - description: History entries - content: - application/json: - schema: - type: object - properties: - items: - type: array - items: - $ref: "#/components/schemas/HistoryEntry" - pagination: - $ref: "#/components/schemas/PaginationInfo" - - /api/history_v2/{prompt_id}: - get: - operationId: getHistoryV2ByPromptId - tags: [history] - summary: Get v2 history for a specific prompt - x-runtime: [cloud] - deprecated: true - description: | - **Deprecated.** This endpoint is superseded by `GET /api/jobs/{prompt_id}`. - Clients should migrate; the endpoint is retained for backward - compatibility but will be removed in a future release. - parameters: - - $ref: "#/components/parameters/ComfyUserHeader" - - name: prompt_id - in: path - description: The prompt ID to fetch history for. - required: true - schema: - type: string - format: uuid - responses: - "200": - description: Single history entry - content: - application/json: - schema: - $ref: "#/components/schemas/HistoryEntry" - "404": - description: Prompt not found - # --------------------------------------------------------------------------- # Upload # --------------------------------------------------------------------------- @@ -690,71 +592,6 @@ paths: "404": description: File not found - /api/viewvideo: - get: - operationId: viewVideo - tags: [view] - summary: View or download a video file (legacy alias) - x-runtime: [cloud] - deprecated: true - description: | - **Deprecated.** This endpoint is an alias of `GET /api/view` added for - legacy history-queue video playback. Callers should use `/api/view` - directly; the endpoint is retained for backward compatibility but will - be removed in a future release. - parameters: - - name: filename - in: query - required: true - schema: - type: string - description: Name of the file to view - - name: type - in: query - schema: - type: string - enum: [input, output, temp] - default: output - description: Directory type - - name: subfolder - in: query - schema: - type: string - description: Subfolder within the directory - - name: preview - in: query - schema: - type: string - description: Preview format hint (e.g. "webp;90") - - name: channel - in: query - schema: - type: string - enum: [rgba, rgb, a] - description: Channel extraction mode - responses: - "200": - description: File content - content: - image/*: - schema: - type: string - format: binary - video/*: - schema: - type: string - format: binary - audio/*: - schema: - type: string - format: binary - application/octet-stream: - schema: - type: string - format: binary - "404": - description: File not found - /api/view_metadata/{folder_name}: get: operationId: viewMetadata @@ -855,32 +692,6 @@ paths: x-runtime: [cloud] description: "[cloud-only] How the templates version was resolved. Local ComfyUI returns null." - /api/logs: - get: - operationId: getLogs - tags: [system] - summary: Get server logs (placeholder) - x-runtime: [cloud] - deprecated: true - description: | - **Deprecated.** This endpoint returns a static placeholder response and - provides no real log data. It is retained only to avoid breaking clients - that still call it. Clients should remove their dependency; the endpoint - will be removed in a future release. - responses: - "200": - description: Static placeholder log response - content: - application/json: - schema: - type: object - properties: - logs: - type: array - items: - type: string - description: Log lines (always empty in current implementation) - # --------------------------------------------------------------------------- # Node / Object Info # --------------------------------------------------------------------------- @@ -2258,7 +2069,6 @@ paths: type: integer description: Number of assets marked as missing - # =========================================================================== # Cloud-runtime FE-facing operations # @@ -2309,7 +2119,11 @@ paths: operationId: getCloudJobStatus tags: [queue] summary: Get status of a cloud job - description: "[cloud-only] Returns the current execution status of a cloud job." + deprecated: true + description: | + **Deprecated.** This endpoint is superseded by `GET /api/jobs/{job_id}`. + Clients should migrate; the endpoint is retained for backward + compatibility but will be removed in a future release. x-runtime: [cloud] parameters: - name: job_id @@ -2379,7 +2193,11 @@ paths: operationId: getHistoryV2 tags: [history] summary: Get paginated execution history (v2) - description: "[cloud-only] Returns a paginated list of execution history entries in the v2 format, with richer metadata than the legacy history endpoint." + deprecated: true + description: | + **Deprecated.** This endpoint is superseded by `GET /api/jobs`. + Clients should migrate; the endpoint is retained for backward + compatibility but will be removed in a future release. x-runtime: [cloud] parameters: - name: limit @@ -2418,7 +2236,11 @@ paths: operationId: getHistoryV2ByPromptId tags: [history] summary: Get v2 history for a specific prompt - description: "[cloud-only] Returns the v2 history entry for a specific prompt execution." + deprecated: true + description: | + **Deprecated.** This endpoint is superseded by `GET /api/jobs/{prompt_id}`. + Clients should migrate; the endpoint is retained for backward + compatibility but will be removed in a future release. x-runtime: [cloud] parameters: - name: prompt_id @@ -2453,7 +2275,12 @@ paths: operationId: getCloudLogs tags: [system] summary: Get cloud execution logs - description: "[cloud-only] Returns execution logs for the authenticated user's cloud jobs." + deprecated: true + description: | + **Deprecated.** This endpoint returns a static placeholder response and + provides no real log data. It is retained only to avoid breaking clients + that still call it. Clients should remove their dependency; the endpoint + will be removed in a future release. x-runtime: [cloud] parameters: - name: job_id @@ -5547,7 +5374,12 @@ paths: operationId: viewVideo tags: [view] summary: View or download a video file - description: "[cloud-only] Serves a video file from the output directory. Used by the frontend video player." + deprecated: true + description: | + **Deprecated.** This endpoint is an alias of `GET /api/view` added for + legacy history-queue video playback. Callers should use `/api/view` + directly; the endpoint is retained for backward compatibility but will + be removed in a future release. x-runtime: [cloud] parameters: - name: filename @@ -5700,7 +5532,6 @@ paths: schema: $ref: "#/components/schemas/CloudError" - components: parameters: ComfyUserHeader: @@ -7052,7 +6883,6 @@ components: error: type: string - # ------------------------------------------------------------------- # Cloud-runtime schemas #