chore(openapi): sync shared API contract from cloud@94d0f1b

openapi.yaml

@@ -35,6 +35,10 @@ components:
                     description: Timestamp when the asset was last accessed
                     format: date-time
                     type: string
+                loader_path:
+                    description: The bare value a loader widget consumes for this asset. For models it is the path inside the category folder (e.g. "flux.safetensors" for "models/checkpoints/flux.safetensors"), which is what the model resolver matches. For input/output/temp it is the content hash, because those assets are fetched by hash rather than staged by name — that is the value LoadImage-style widgets must carry. Clients add the "[output]"/"[temp]" annotation from the asset's own type, so it is never included here. Null when no such value can be derived.
+                    nullable: true
+                    type: string
                 metadata:
                     additionalProperties: true
                     description: System-managed metadata from download sources (HuggingFace, CivitAI, etc.) - read-only, not user-modifiable
@@ -165,6 +169,10 @@ components:
                     format: uuid
                     nullable: true
                     type: string
+                loader_path:
+                    description: The bare value a loader widget consumes for this asset. For models it is the path inside the category folder (e.g. "flux.safetensors" for "models/checkpoints/flux.safetensors"), which is what the model resolver matches. For input/output/temp it is the content hash, because those assets are fetched by hash rather than staged by name — that is the value LoadImage-style widgets must carry. Clients add the "[output]"/"[temp]" annotation from the asset's own type, so it is never included here. Null when no such value can be derived.
+                    nullable: true
+                    type: string
                 mime_type:
                     description: Updated MIME type of the asset
                     type: string
@@ -188,6 +196,31 @@ components:
                 - id
                 - updated_at
             type: object
+        ChurnkeyAuthResponse:
+            description: |
+                Credentials the Churnkey embed requires to launch the cancel flow.
+                `auth_hash` is hex-encoded HMAC-SHA256 of `customer_id` signed with the
+                server's CHURNKEY_HMAC_SECRET; it is bound to that single customer ID
+                and must not be reused for other customers.
+            properties:
+                auth_hash:
+                    description: Hex-encoded HMAC-SHA256(customer_id, CHURNKEY_HMAC_SECRET)
+                    type: string
+                customer_id:
+                    description: Stripe customer ID for the workspace
+                    type: string
+                mode:
+                    description: Churnkey environment matching the configured app
+                    enum:
+                        - live
+                        - test
+                        - sandbox
+                    type: string
+            required:
+                - customer_id
+                - auth_hash
+                - mode
+            type: object
         CreateWorkflowRequest:
             description: Request body for creating a new saved workflow.
             properties:
@@ -511,6 +544,25 @@ components:
             required:
                 - history
             type: object
+        JobAssetsResponse:
+            description: Paginated list of the assets produced by a single job.
+            properties:
+                assets:
+                    description: The job's output assets for the requested page (empty when the job produced none)
+                    items:
+                        $ref: '#/components/schemas/JobOutputAsset'
+                    type: array
+                job_id:
+                    description: ID of the job these assets belong to
+                    format: uuid
+                    type: string
+                pagination:
+                    $ref: '#/components/schemas/PaginationInfo'
+            required:
+                - job_id
+                - assets
+                - pagination
+            type: object
         JobCancelResponse:
             description: Response for POST /api/jobs/{job_id}/cancel. Returned on both fresh cancels and idempotent no-ops.
             properties:
@@ -565,6 +617,9 @@ components:
                     additionalProperties: true
                     description: Primary preview output (only for terminal states)
                     type: object
+                previewable_outputs_count:
+                    description: Count of outputs classified as previewable media types (images, video, audio, 3D, text) — a subset of outputs_count (omitted for non-terminal states)
+                    type: integer
                 status:
                     description: User-friendly job status
                     enum:
@@ -597,6 +652,13 @@ components:
                 workflow_id:
                     description: UUID identifying the workflow graph definition
                     type: string
+                workflow_version_id:
+                    description: |
+                        UUID of the cloud workflow version this job is pinned to, if the
+                        submission carried one (see PromptRequest's workflow_version_id).
+                        Absent for jobs submitted without that association, including
+                        every job submitted through the public API v2 today.
+                    type: string
                 workspace_id:
                     description: |
                         ID of the workspace that owns this job. A successful (200)
@@ -645,6 +707,9 @@ components:
                     additionalProperties: true
                     description: Primary preview output (only present for terminal states)
                     type: object
+                previewable_outputs_count:
+                    description: Count of outputs classified as previewable media types (images, video, audio, 3D, text) — a subset of outputs_count (omitted for non-terminal states)
+                    type: integer
                 status:
                     description: User-friendly job status
                     enum:
@@ -662,6 +727,56 @@ components:
                 - status
                 - create_time
             type: object
+        JobOutputAsset:
+            description: |
+                An asset produced by a job, enriched with the per-output node context
+                (`node_id`, `output_key`, `output_index`) correlated from the job's
+                execution outputs by content hash. The node-context fields are null
+                when the asset cannot be matched to an output entry.
+            properties:
+                created_at:
+                    description: Timestamp when the asset was created
+                    format: date-time
+                    type: string
+                hash:
+                    description: Blake3 hash of the asset content.
+                    pattern: ^blake3:[a-f0-9]{64}$
+                    type: string
+                id:
+                    description: Unique identifier for the asset
+                    format: uuid
+                    type: string
+                mime_type:
+                    description: MIME type of the asset
+                    type: string
+                name:
+                    description: Name of the asset file
+                    type: string
+                node_id:
+                    description: ID of the workflow node that produced this asset, if known
+                    nullable: true
+                    type: string
+                output_index:
+                    description: Zero-based index of this asset within the node's output slot, if known
+                    nullable: true
+                    type: integer
+                output_key:
+                    description: Output slot key under the producing node (e.g. "images"), if known
+                    nullable: true
+                    type: string
+                preview_url:
+                    description: Relative URL for asset preview/thumbnail
+                    format: uri-reference
+                    type: string
+                size:
+                    description: Size of the asset in bytes
+                    format: int64
+                    type: integer
+            required:
+                - id
+                - name
+                - created_at
+            type: object
         JobStatusResponse:
             description: Job status information
             properties:
@@ -1522,7 +1637,11 @@ paths:
             operationId: listAssets
             parameters:
                 - deprecated: true
-                  description: 'Deprecated alias of tags_all: filter assets that have ALL of these tags'
+                  description: |
+                    Deprecated alias for `tags_all`, kept permanently for existing
+                    callers. Filter assets that have ALL of these tags. Combining it
+                    with `tags_all`, or exceeding 100 tags (counted after removing
+                    empty values and duplicates), returns 400 `INVALID_TAG_FILTER`.
                   explode: false
                   in: query
                   name: include_tags
@@ -1532,7 +1651,11 @@ paths:
                     type: array
                   style: form
                 - deprecated: true
-                  description: 'Deprecated alias of tags_none: exclude assets that have ANY of these tags'
+                  description: |
+                    Deprecated alias for `tags_none`, kept permanently for existing
+                    callers. Exclude assets that have ANY of these tags. Combining it
+                    with `tags_none`, or exceeding 100 tags (counted after removing
+                    empty values and duplicates), returns 400 `INVALID_TAG_FILTER`.
                   explode: false
                   in: query
                   name: exclude_tags
@@ -1541,7 +1664,14 @@ paths:
                         type: string
                     type: array
                   style: form
-                - description: Filter assets that have ALL of these tags
+                - description: |
+                    Filter assets that have ALL of these tags. Tag values are opaque
+                    byte-strings compared exactly and case-sensitively; unknown tags
+                    are not an error — they simply match nothing. Replaces the
+                    deprecated `include_tags`. Sending both spellings, listing the
+                    same tag here and in `tags_none`, or exceeding 100 tags per list
+                    (counted after removing empty values and duplicates) returns 400
+                    `INVALID_TAG_FILTER`.
                   explode: false
                   in: query
                   name: tags_all
@@ -1550,7 +1680,14 @@ paths:
                         type: string
                     type: array
                   style: form
-                - description: Filter assets that have AT LEAST ONE of these tags
+                - description: |
+                    Filter assets that have AT LEAST ONE of these tags. Combines with
+                    `tags_all`/`tags_none` by intersection (`tags_none` always wins;
+                    overlap with `tags_none` is allowed and leaves a dead term).
+                    Supplying a positive tag filter (`tags_any`, `tags_all`, or
+                    `include_tags`) replaces the default category filter that is
+                    otherwise applied. Lists over 100 tags (counted after removing
+                    empty values and duplicates) return 400 `INVALID_TAG_FILTER`.
                   explode: false
                   in: query
                   name: tags_any
@@ -1559,7 +1696,11 @@ paths:
                         type: string
                     type: array
                   style: form
-                - description: Exclude assets that have ANY of these tags
+                - description: |
+                    Exclude assets that have ANY of these tags. Replaces the
+                    deprecated `exclude_tags`. Sending both spellings, or exceeding
+                    100 tags per list (counted after removing empty values and
+                    duplicates), returns 400 `INVALID_TAG_FILTER`.
                   explode: false
                   in: query
                   name: tags_none
@@ -2342,7 +2483,11 @@ paths:
             operationId: getAssetTagHistogram
             parameters:
                 - deprecated: true
-                  description: 'Deprecated alias of tags_all: filter assets that have ALL of these tags'
+                  description: |
+                    Deprecated alias for `tags_all`, kept permanently for existing
+                    callers. Filter assets that have ALL of these tags. The same
+                    combination and list-size rules as on `/api/assets` apply
+                    (400 `INVALID_TAG_FILTER`).
                   explode: false
                   in: query
                   name: include_tags
@@ -2352,7 +2497,11 @@ paths:
                     type: array
                   style: form
                 - deprecated: true
-                  description: 'Deprecated alias of tags_none: exclude assets that have ANY of these tags'
+                  description: |
+                    Deprecated alias for `tags_none`, kept permanently for existing
+                    callers. Exclude assets that have ANY of these tags. The same
+                    combination and list-size rules as on `/api/assets` apply
+                    (400 `INVALID_TAG_FILTER`).
                   explode: false
                   in: query
                   name: exclude_tags
@@ -2361,7 +2510,10 @@ paths:
                         type: string
                     type: array
                   style: form
-                - description: Filter assets that have ALL of these tags
+                - description: |
+                    Filter assets that have ALL of these tags. Replaces the deprecated
+                    `include_tags`. The same combination and list-size rules as on
+                    `/api/assets` apply (400 `INVALID_TAG_FILTER`).
                   explode: false
                   in: query
                   name: tags_all
@@ -2370,7 +2522,11 @@ paths:
                         type: string
                     type: array
                   style: form
-                - description: Filter assets that have AT LEAST ONE of these tags
+                - description: |
+                    Filter assets that have AT LEAST ONE of these tags. Combines with
+                    `tags_all`/`tags_none` by intersection (`tags_none` always wins).
+                    The same combination and list-size rules as on `/api/assets` apply
+                    (400 `INVALID_TAG_FILTER`).
                   explode: false
                   in: query
                   name: tags_any
@@ -2379,7 +2535,10 @@ paths:
                         type: string
                     type: array
                   style: form
-                - description: Exclude assets that have ANY of these tags
+                - description: |
+                    Exclude assets that have ANY of these tags. Replaces the deprecated
+                    `exclude_tags`. The same combination and list-size rules as on
+                    `/api/assets` apply (400 `INVALID_TAG_FILTER`).
                   explode: false
                   in: query
                   name: tags_none
@@ -2440,6 +2599,49 @@ paths:
             summary: Get tag histogram for filtered assets
             tags:
                 - file
+    /api/billing/churnkey/auth:
+        get:
+            description: |
+                Returns the Stripe customer identifier and a server-signed
+                HMAC-SHA256 of the customer ID, used to launch the Churnkey-hosted
+                cancellation flow embed.
+            operationId: getChurnkeyAuth
+            responses:
+                "200":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ChurnkeyAuthResponse'
+                    description: Success
+                "401":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: Unauthorized
+                "404":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: Workspace has no Stripe customer (never subscribed)
+                "500":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: Internal server error
+                "503":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: Churnkey is not configured on the server
+            security:
+                - BearerAuth: []
+            summary: Get Churnkey HMAC auth credentials
+            tags:
+                - billing
     /api/embeddings:
         get:
             description: Returns the list of text-encoder embeddings available on disk.
@@ -2460,9 +2662,10 @@ paths:
                 Returns a list of model folders available in the system.
                 This is an experimental endpoint that replaces the legacy /models endpoint.
                 Each folder's name is the identifier to pass to /api/experiment/models/{folder}.
-                Once the model_type migration is active the names are model_type folder_names
+                The folder vocabulary is resolved per request from the caller's identity: where the
-                (e.g. `ultralytics_bbox`); a folder with no folder_name mapping is returned by
+                model_type migration is active for that caller the names are model_type folder_names
-                its directory path.
+                (e.g. `ultralytics_bbox`), and a folder with no folder_name mapping is returned by its
+                directory path. An authenticated response can therefore differ from an anonymous one.
             operationId: getModelFolders
             responses:
                 "200":
@@ -2479,7 +2682,10 @@ paths:
                             schema:
                                 $ref: '#/components/schemas/ErrorResponse'
                     description: Internal server error
-            security: []
+            security:
+                - ApiKeyAuth: []
+                - BearerAuth: []
+                - {}
             summary: Get available model folders
             tags:
                 - file
@@ -2488,6 +2694,10 @@ paths:
             description: |
                 Returns a list of models available in the specified folder.
                 This is an experimental endpoint that provides enhanced model information.
+                Accepted folder identifiers are those returned by /api/experiment/models for the same
+                caller. That vocabulary is request-scoped, so list folders and fetch a folder's models
+                with the same credentials — a name obtained anonymously may not resolve when
+                authenticated, and vice versa.
             operationId: getModelsInFolder
             parameters:
                 - description: The folder name to list models from
@@ -2518,7 +2728,10 @@ paths:
                             schema:
                                 $ref: '#/components/schemas/ErrorResponse'
                     description: Internal server error
-            security: []
+            security:
+                - ApiKeyAuth: []
+                - BearerAuth: []
+                - {}
             summary: Get models in a specific folder
             tags:
                 - file
@@ -3155,6 +3368,74 @@ paths:
             summary: Get full job details
             tags:
                 - workflow
+    /api/jobs/{job_id}/assets:
+        get:
+            description: |
+                Retrieve a paginated list of the assets produced by a specific job,
+                enriched with the per-output node context (`node_id`, `output_key`,
+                `output_index`) correlated from the job's execution outputs by content
+                hash. Unlike `GET /api/assets?job_ids={id}`, this endpoint is scoped to a
+                single job and carries node-level placement, making it suited to job
+                output views rather than the general asset browser. Returns an empty
+                `assets` array for jobs that produced no assets.
+            operationId: getJobAssets
+            parameters:
+                - description: Job identifier (UUID)
+                  in: path
+                  name: job_id
+                  required: true
+                  schema:
+                    format: uuid
+                    type: string
+                - description: Maximum number of assets to return (1-500)
+                  in: query
+                  name: limit
+                  schema:
+                    default: 20
+                    maximum: 500
+                    minimum: 1
+                    type: integer
+                - description: Number of assets to skip for pagination
+                  in: query
+                  name: offset
+                  schema:
+                    default: 0
+                    minimum: 0
+                    type: integer
+            responses:
+                "200":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/JobAssetsResponse'
+                    description: Success - Job assets returned
+                "400":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: Invalid request parameters
+                "401":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: Unauthorized - Authentication required
+                "404":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: Job not found or does not belong to the user
+                "500":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/ErrorResponse'
+                    description: Internal server error
+            summary: List a job's output assets
+            tags:
+                - workflow
     /api/jobs/{job_id}/cancel:
         post:
             description: |
@@ -3360,6 +3641,12 @@ paths:
                             schema:
                                 $ref: '#/components/schemas/PromptErrorResponse'
                     description: Payment required - Insufficient credits
+                "403":
+                    content:
+                        application/json:
+                            schema:
+                                $ref: '#/components/schemas/PromptErrorResponse'
+                    description: Workspace governance policy blocks one or more partner providers (error.type PARTNER_NODE_DISABLED; error.class_types lists the offending nodes, error.providers the disabled providers)
                 "413":
                     content:
                         application/json:
@@ -3371,7 +3658,7 @@ paths:
                         application/json:
                             schema:
                                 $ref: '#/components/schemas/PromptErrorResponse'
-                    description: Payment required - User has not paid
+                    description: 'Retryable backpressure. Two distinct causes, disambiguated by the body''s `error.type`, NOT by parsing `error.message`: `PAYMENT_REQUIRED` / `FREE_TIER_UNAVAILABLE` / `FREE_TIER_EXHAUSTED` / `PARTNER_NODE_PAYMENT_REQUIRED` (a billing gate - retrying without paying never succeeds), or `QUEUE_LIMIT` (this workspace''s bounded job queue is full - retrying after some queued jobs complete will succeed).'
                 "500":
                     content:
                         application/json:
@@ -5210,6 +5497,8 @@ tags:
       name: user
     - description: Background task management
       name: task
+    - description: Workspace billing and subscription management
+      name: billing
     - description: Workflow storage and version management
       name: workflows
     - description: Job queue state and control