From fb097bedc2af8cc7499fba8ab6da8811ecc40491 Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Tue, 12 May 2026 11:06:28 -0700
Subject: [PATCH] Mark deprecated cloud-runtime endpoints in spec (#13789)
MIME-Version: 1.0
Content-Type: text/plain; charset=UTF-8
Content-Transfer-Encoding: 8bit

* Mark deprecated cloud-runtime endpoints in openapi.yaml

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 <MillerMedia@users.noreply.github.com>

* 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 | 35 +++++++++++++++++++++++++++--------
 1 file changed, 27 insertions(+), 8 deletions(-)

diff --git a/openapi.yaml b/openapi.yaml
index d4c9e67ca..96be4c1d5 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -2071,7 +2071,6 @@ paths:
                     type: integer
                     description: Number of assets marked as missing
 
-
   # ===========================================================================
   # Cloud-runtime FE-facing operations
   #
@@ -2122,7 +2121,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
@@ -2192,7 +2195,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
@@ -2231,7 +2238,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
@@ -2266,7 +2277,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
@@ -5370,7 +5386,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
@@ -5523,7 +5544,6 @@ paths:
               schema:
                 $ref: "#/components/schemas/CloudError"
 
-
 components:
   parameters:
     ComfyUserHeader:
@@ -6875,7 +6895,6 @@ components:
         error:
           type: string
 
-
     # -------------------------------------------------------------------
     # Cloud-runtime schemas
     #