feat: add cloud-specific fields to OSS openapi.yaml as nullable (#13623)

* feat: add cloud-specific fields to OSS openapi.yaml as nullable

Add cross-runtime fields with x-runtime: [cloud] extension and [cloud-only]
description prefix per the convention established in BE-613. All new fields
are nullable and not in required arrays, so they are purely additive.

/api/features response:
- max_upload_size (integer, int64)
- free_tier_credits (integer, int32)
- posthog_api_host (string, uri)
- max_concurrent_jobs (integer, int32)
- workflow_templates_version (string)
- workflow_templates_source (string, enum)

PromptRequest schema:
- workflow_id (string, uuid)
- workflow_version_id (string, uuid)

POST /api/assets:
- id field (uuid) on multipart/form-data for idempotent creation
- application/json alternate content-type for URL-based uploads

POST /api/assets/from-hash:
- mime_type (string) to preserve type without re-inspection

PUT /api/assets/{id}:
- mime_type (string) for overriding auto-detection

GET /api/assets additional query parameters:
- job_ids (string) — filter by associated job UUIDs
- include_public (boolean) — include workspace-public assets
- asset_hash (string) — filter by exact content hash

Resolves: BE-613
Blocks: BE-364, BE-361, BE-363

Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com>

* fix(openapi): address CodeRabbit feedback (BE-613)

- max_upload_size is set in both runtimes via SERVER_FEATURE_FLAGS;
  drop the cloud-only / nullable tagging.
- Require `url` on the application/json POST /api/assets body so the
  contract is enforceable by validators and codegen.

---------

Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com>

openapi.yaml

@@ -631,7 +631,7 @@ paths:
       operationId: getFeatures
       tags: [system]
       summary: Get enabled feature flags
-      description: Returns a dictionary of feature flag names to their enabled state.
+      description: Returns a dictionary of feature flag names to their enabled state. Cloud deployments may include additional typed fields alongside the boolean flags.
       responses:
         "200":
           description: Feature flags
@@ -641,6 +641,43 @@ paths:
                 type: object
                 additionalProperties:
                   type: boolean
+                properties:
+                  max_upload_size:
+                    type: integer
+                    format: int64
+                    minimum: 0
+                    description: "Maximum file upload size in bytes."
+                  free_tier_credits:
+                    type: integer
+                    format: int32
+                    minimum: 0
+                    nullable: true
+                    x-runtime: [cloud]
+                    description: "[cloud-only] Credits available to free-tier users. Local ComfyUI returns null."
+                  posthog_api_host:
+                    type: string
+                    format: uri
+                    nullable: true
+                    x-runtime: [cloud]
+                    description: "[cloud-only] PostHog analytics proxy URL for frontend telemetry. Local ComfyUI returns null."
+                  max_concurrent_jobs:
+                    type: integer
+                    format: int32
+                    minimum: 0
+                    nullable: true
+                    x-runtime: [cloud]
+                    description: "[cloud-only] Maximum concurrent jobs the authenticated user can run. Local ComfyUI returns null."
+                  workflow_templates_version:
+                    type: string
+                    nullable: true
+                    x-runtime: [cloud]
+                    description: "[cloud-only] Version identifier for the workflow templates bundle. Local ComfyUI returns null."
+                  workflow_templates_source:
+                    type: string
+                    nullable: true
+                    enum: [dynamic_config_override, workflow_templates_version_json]
+                    x-runtime: [cloud]
+                    description: "[cloud-only] How the templates version was resolved. Local ComfyUI returns null."
 
   # ---------------------------------------------------------------------------
   # Node / Object Info
@@ -1497,6 +1534,24 @@ paths:
             type: string
             enum: [asc, desc]
           description: Sort direction
+        - name: job_ids
+          in: query
+          schema:
+            type: string
+          x-runtime: [cloud]
+          description: "[cloud-only] Comma-separated UUIDs to filter assets by associated job."
+        - name: include_public
+          in: query
+          schema:
+            type: boolean
+          x-runtime: [cloud]
+          description: "[cloud-only] Include workspace-public assets in addition to the caller's own."
+        - name: asset_hash
+          in: query
+          schema:
+            type: string
+          x-runtime: [cloud]
+          description: "[cloud-only] Filter by exact content hash."
       responses:
         "200":
           description: Asset list
@@ -1542,6 +1597,49 @@ paths:
                   type: string
                   format: uuid
                   description: ID of an existing asset to use as the preview image
+                id:
+                  type: string
+                  format: uuid
+                  nullable: true
+                  x-runtime: [cloud]
+                  description: "[cloud-only] Client-supplied asset ID for idempotent creation. If an asset with this ID already exists, the existing asset is returned."
+          application/json:
+            schema:
+              type: object
+              x-runtime: [cloud]
+              description: "[cloud-only] URL-based asset upload. Caller supplies a URL instead of a file body; the server fetches the content."
+              required:
+                - url
+              properties:
+                url:
+                  type: string
+                  format: uri
+                  description: "[cloud-only] URL of the file to import as an asset"
+                name:
+                  type: string
+                  description: Display name for the asset
+                tags:
+                  type: string
+                  description: Comma-separated tags
+                user_metadata:
+                  type: string
+                  description: JSON-encoded user metadata
+                hash:
+                  type: string
+                  description: "Blake3 hash of the file content (e.g. blake3:abc123...)"
+                mime_type:
+                  type: string
+                  description: MIME type of the file (overrides auto-detected type)
+                preview_id:
+                  type: string
+                  format: uuid
+                  description: ID of an existing asset to use as the preview image
+                id:
+                  type: string
+                  format: uuid
+                  nullable: true
+                  x-runtime: [cloud]
+                  description: "[cloud-only] Client-supplied asset ID for idempotent creation. If an asset with this ID already exists, the existing asset is returned."
       responses:
         "201":
           description: Asset created
@@ -1580,6 +1678,11 @@ paths:
                 user_metadata:
                   type: object
                   additionalProperties: true
+                mime_type:
+                  type: string
+                  nullable: true
+                  x-runtime: [cloud]
+                  description: "[cloud-only] MIME type of the content, so the type is preserved without re-inspecting content. Ignored by local ComfyUI."
       responses:
         "201":
           description: Asset created from hash
@@ -1644,6 +1747,11 @@ paths:
                   type: string
                   format: uuid
                   description: ID of the asset to use as the preview
+                mime_type:
+                  type: string
+                  nullable: true
+                  x-runtime: [cloud]
+                  description: "[cloud-only] MIME type override when auto-detection was wrong. Ignored by local ComfyUI."
       responses:
         "200":
           description: Asset updated
@@ -2004,21 +2112,13 @@ components:
           format: uuid
           nullable: true
           x-runtime: [cloud]
-          description: |
-            UUID identifying a hosted-cloud workflow entity to associate with this
-            job. Local ComfyUI doesn't track workflow entities and returns `null`
-            (or omits the field). The `x-runtime: [cloud]` extension marks this
-            as populated only by the hosted-cloud runtime; absence of the tag
-            means a field is populated by all runtimes.
+          description: "[cloud-only] Cloud workflow entity ID for tracking and gallery association. Ignored by local ComfyUI."
         workflow_version_id:
           type: string
           format: uuid
           nullable: true
           x-runtime: [cloud]
-          description: |
-            UUID identifying a hosted-cloud workflow version to associate with
-            this job. Local ComfyUI returns `null` (or omits the field). See
-            `workflow_id` above for `x-runtime` semantics.
+          description: "[cloud-only] Cloud workflow version ID for pinning execution to a specific version. Ignored by local ComfyUI."
 
     PromptResponse:
       type: object