From e9e30553ca1fdff73483a7a65bf57a550ccb7598 Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Tue, 26 May 2026 14:19:29 -0700
Subject: [PATCH] openapi: document QueueManageResponse body on POST /api/queue

The Cloud runtime returns a JSON body from POST /api/queue describing which
prompts were deleted and whether the queue was cleared. The spec previously
declared a bare 200 with no schema, so generated clients had no type for the
response.

Adds a QueueManageResponse schema ({deleted, cleared}) and references it from
the 200 response. Tagged x-runtime: [cloud] with a [cloud-only] description:
local ComfyUI returns an empty 200 body, so both fields are nullable.
---
 openapi.yaml | 24 +++++++++++++++++++++++-
 1 file changed, 23 insertions(+), 1 deletion(-)

diff --git a/openapi.yaml b/openapi.yaml
index 502e518c7..4ec35a9cf 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -275,7 +275,10 @@ paths:
       responses:
         "200":
           description: Queue updated
-
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/QueueManageResponse"
         '400':
           description: Invalid request parameters
           content:
@@ -7466,6 +7469,25 @@ components:
             type: string
           description: Array of prompt IDs to delete from queue
 
+    QueueManageResponse:
+      type: object
+      x-runtime: [cloud]
+      description: >-
+        [cloud-only] Result of a queue mutation. The Cloud runtime returns which
+        items were deleted and whether the queue was cleared; local ComfyUI
+        returns an empty 200 body.
+      properties:
+        deleted:
+          type: array
+          nullable: true
+          items:
+            type: string
+          description: Prompt IDs that were deleted from the queue.
+        cleared:
+          type: boolean
+          nullable: true
+          description: Whether the queue was cleared.
+
     # -------------------------------------------------------------------
     # History
     # -------------------------------------------------------------------