From 4d50729efb4e4357e7f10a39f5ecd4008934d1e0 Mon Sep 17 00:00:00 2001
From: Matt Miller <mattmiller@comfy.org>
Date: Tue, 26 May 2026 14:32:34 -0700
Subject: [PATCH] openapi: add Cloud-runtime fields (workflow_id,
 execution_error) to JobEntry (#14119)

* openapi: add Cloud-runtime fields workflow_id, execution_error to JobEntry

The Cloud runtime returns two additional fields on JobEntry that the spec
didn't declare:

- workflow_id: UUID of the Cloud workflow entity the job is associated with
- execution_error: structured ComfyUI execution error for failed jobs
  (reuses the existing ExecutionError schema)

Both tagged x-runtime: [cloud] with [cloud-only] descriptions; local ComfyUI
does not populate them.

* openapi: document Cloud-runtime request fields on POST /api/assets/export (#14120)

The Cloud runtime accepts three request fields on /api/assets/export that the
spec didn't declare:

- job_ids: include all assets associated with the given jobs
- naming_strategy: how to name files in the ZIP (enum, default group_by_job_time)
- job_asset_name_filters: optional per-job asset-name allowlist

Also drops asset_ids from required: the runtime supports exporting by job_ids
alone, so neither field is individually required.

/api/assets/export is already x-runtime: [cloud]; these are plain field
additions under that endpoint-level tag.
---
 openapi.yaml | 32 +++++++++++++++++++++++++++++---
 1 file changed, 29 insertions(+), 3 deletions(-)

diff --git a/openapi.yaml b/openapi.yaml
index e62d0ab67..f801a39d9 100644
--- a/openapi.yaml
+++ b/openapi.yaml
@@ -3095,18 +3095,34 @@ paths:
           application/json:
             schema:
               type: object
-              required:
-                - asset_ids
               properties:
+                job_ids:
+                  type: array
+                  items:
+                    type: string
+                  description: Job IDs whose associated assets should all be included in the ZIP bundle.
                 asset_ids:
                   type: array
                   items:
                     type: string
                     format: uuid
-                  description: IDs of assets to export
+                  description: Asset IDs to include in the ZIP bundle. Additive to assets associated with provided job IDs.
                 export_name:
                   type: string
                   description: Name for the export archive
+                naming_strategy:
+                  type: string
+                  enum: [group_by_job_id, preserve, asset_id, group_by_job_time]
+                  default: group_by_job_time
+                  description: "Strategy for naming files in the ZIP: group by job ID, preserve original names, use the asset ID, or group by job creation time."
+                job_asset_name_filters:
+                  type: object
+                  additionalProperties:
+                    type: array
+                    minItems: 1
+                    items:
+                      type: string
+                  description: Optional per-job asset name filters. When provided for a job ID, only assets whose name matches one of the listed names are included.
       responses:
         "202":
           description: Export task accepted
@@ -7565,6 +7581,16 @@ components:
         outputs_count:
           type: integer
           description: Total number of output files
+        workflow_id:
+          type: string
+          nullable: true
+          x-runtime: [cloud]
+          description: "[cloud-only] UUID of the Cloud workflow entity this job is associated with. Local ComfyUI returns null."
+        execution_error:
+          x-runtime: [cloud]
+          description: "[cloud-only] Detailed execution error from ComfyUI for failed jobs. Absent on local ComfyUI."
+          allOf:
+            - $ref: "#/components/schemas/ExecutionError"
 
     JobDetailResponse:
       type: object