openapi.yaml

components:
    schemas:
        Asset:
            description: Represents a user-owned asset (image, video, or other generated output).
            properties:
                created_at:
                    description: Timestamp when the asset was created
                    format: date-time
                    type: string
                display_name:
                    description: Display name of the asset. Mirrors name for backwards compatibility.
                    nullable: true
                    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
                is_immutable:
                    description: Whether this asset is immutable (cannot be modified or deleted)
                    type: boolean
                job_id:
                    description: ID of the job that created this asset, if available
                    format: uuid
                    nullable: true
                    type: string
                last_access_time:
                    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
                    readOnly: true
                    type: object
                mime_type:
                    description: MIME type of the asset
                    type: string
                name:
                    description: Name of the asset file
                    type: string
                preview_id:
                    description: ID of the preview asset if available
                    format: uuid
                    nullable: true
                    type: string
                preview_url:
                    description: URL for asset preview/thumbnail
                    format: uri
                    type: string
                short_url:
                    description: Durable, owner-gated short link to this asset's content (relative `/api/s/{id}` path). Stable across the underlying signed URL's expiry — resolving it re-mints a fresh signed URL on every request — so it is safe to persist or share into chat, unlike `preview_url`. Only the minting user can resolve it. Omitted when the short-link surface is disabled or the asset has no resolvable content hash.
                    nullable: true
                    type: string
                    x-runtime:
                        - cloud
                size:
                    description: Size of the asset in bytes
                    format: int64
                    type: integer
                tags:
                    description: Tags associated with the asset
                    items:
                        type: string
                    type: array
                updated_at:
                    description: Timestamp when the asset was last updated
                    format: date-time
                    type: string
                user_metadata:
                    additionalProperties: true
                    description: Custom user metadata for the asset
                    type: object
            required:
                - id
                - name
                - created_at
                - updated_at
            type: object
        AssetCreated:
            allOf:
                - $ref: '#/components/schemas/Asset'
                - properties:
                    created_new:
                        description: Whether this was a new asset creation (true) or returned existing (false)
                        type: boolean
                  required:
                    - created_new
                  type: object
            description: Response returned when a new asset is successfully created.
        AssetInfo:
            description: Lightweight asset reference used in workflow publishing payloads.
            properties:
                id:
                    description: Asset identifier.
                    type: string
                in_library:
                    description: Whether the caller already owns this asset.
                    type: boolean
                model:
                    description: Whether this asset is a model.
                    type: boolean
                name:
                    type: string
                preview_url:
                    description: Signed URL for previewing the asset.
                    type: string
                public:
                    description: Whether this is a public (platform-provided) asset.
                    type: boolean
                storage_url:
                    type: string
            required:
                - id
                - name
                - preview_url
                - storage_url
                - model
                - public
                - in_library
            type: object
        AssetTagHistogramResponse:
            description: Histogram of tag counts used for refining asset search results.
            properties:
                tag_counts:
                    additionalProperties:
                        type: integer
                    description: Map of tag names to their occurrence counts on matching assets
                    example:
                        checkpoint: 32
                        lora: 193
                        vae: 6
                    type: object
            required:
                - tag_counts
            type: object
        AssetUpdated:
            description: Response returned when an existing asset is successfully updated.
            properties:
                display_name:
                    description: Display name of the asset. Mirrors name for backwards compatibility.
                    nullable: true
                    type: string
                hash:
                    description: Blake3 hash of the asset content.
                    pattern: ^blake3:[a-f0-9]{64}$
                    type: string
                id:
                    description: Asset ID
                    format: uuid
                    type: string
                job_id:
                    description: ID of the job that created this asset, if available
                    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
                name:
                    description: Updated name of the asset
                    type: string
                tags:
                    description: Tags associated with the asset
                    items:
                        type: string
                    type: array
                updated_at:
                    description: Timestamp of the update
                    format: date-time
                    type: string
                user_metadata:
                    additionalProperties: true
                    description: Updated custom metadata
                    type: object
            required:
                - 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:
                default_view:
                    description: Default view mode
                    enum:
                        - workflow
                        - app
                    type: string
                description:
                    description: Description of the workflow
                    type: string
                forked_from_workflow_id:
                    description: ID of the source workflow if forked
                    type: string
                forked_from_workflow_version_id:
                    description: ID of the source workflow version if forked
                    type: string
                name:
                    description: Display name for the workflow
                    type: string
                workflow_json:
                    additionalProperties: true
                    description: The ComfyUI workflow JSON
                    type: object
            required:
                - workflow_json
            type: object
        CreateWorkflowVersionRequest:
            description: Request body for creating a new version of a saved workflow.
            properties:
                base_version:
                    description: The version number this change is based on (for optimistic concurrency)
                    type: integer
                workflow_json:
                    additionalProperties: true
                    description: The updated ComfyUI workflow JSON
                    type: object
            required:
                - base_version
                - workflow_json
            type: object
        ErrorResponse:
            description: Standard error response with a machine-readable code and human-readable message.
            properties:
                code:
                    type: string
                details:
                    additionalProperties: true
                    description: Optional open object carrying structured, machine-readable context about the error (e.g. offending field names, validation specifics). Absent for most errors; consumers must not assume any particular shape.
                    type: object
                message:
                    type: string
            required:
                - code
                - message
            type: object
        ExecutionError:
            description: Detailed execution error information from ComfyUI
            properties:
                current_inputs:
                    additionalProperties: true
                    description: Input values at time of failure (empty object if not available)
                    type: object
                current_outputs:
                    additionalProperties: true
                    description: Output values at time of failure (empty object if not available)
                    type: object
                exception_message:
                    description: Human-readable error message
                    type: string
                exception_type:
                    description: Python exception type (e.g., "RuntimeError")
                    type: string
                node_id:
                    description: ID of the node that failed
                    type: string
                node_type:
                    description: Type name of the node (e.g., "KSampler")
                    type: string
                traceback:
                    description: Array of traceback lines (empty array if not available)
                    items:
                        type: string
                    type: array
            required:
                - node_id
                - node_type
                - exception_message
                - exception_type
                - traceback
                - current_inputs
                - current_outputs
            type: object
        FeedbackRequest:
            description: Request to submit user feedback
            properties:
                content:
                    description: The feedback content or message
                    type: string
                metadata:
                    additionalProperties: true
                    description: Additional metadata about the feedback
                    type: object
                rating:
                    description: User's rating of ComfyUI Cloud experience (1-5 stars)
                    maximum: 5
                    minimum: 1
                    type: integer
                type:
                    description: Type of feedback being submitted
                    enum:
                        - missing_nodes
                        - general
                        - missing_models
                    type: string
            required:
                - type
            type: object
        FeedbackResponse:
            description: Response after submitting feedback
            type: object
        ForkWorkflowRequest:
            description: Request body for forking an existing workflow into the user's account.
            properties:
                name:
                    description: Name for the forked workflow
                    type: string
                source_version:
                    description: Version number to fork from
                    type: integer
            required:
                - source_version
            type: object
        GetUserDataResponseFull:
            description: List of user data file entries (each with path, size, and modification time) returned when full_info=true.
            items:
                $ref: '#/components/schemas/GetUserDataResponseFullFile'
            type: array
        GetUserDataResponseFullFile:
            description: Individual file entry within a full user data response.
            properties:
                modified:
                    description: UNIX timestamp of the last modification in milliseconds.
                    format: int64
                    type: integer
                path:
                    description: File name or path relative to the user directory.
                    type: string
                size:
                    description: File size in bytes.
                    type: integer
            type: object
        GlobalSubgraphData:
            description: Full data for a global subgraph blueprint
            properties:
                data:
                    description: The full subgraph JSON data as a string
                    type: string
                info:
                    description: Additional information about the subgraph
                    properties:
                        node_pack:
                            description: The node pack/module that provides this subgraph
                            type: string
                    required:
                        - node_pack
                    type: object
                name:
                    description: Display name of the subgraph blueprint
                    type: string
                source:
                    description: Source type of the subgraph - "templates" for workflow templates or "custom_node" for custom node subgraphs
                    type: string
            required:
                - source
                - name
                - info
                - data
            type: object
        GlobalSubgraphInfo:
            description: Metadata for a global subgraph blueprint (without full data)
            properties:
                data:
                    description: The full subgraph JSON data (may be empty in list view)
                    type: string
                info:
                    description: Additional information about the subgraph
                    properties:
                        node_pack:
                            description: The node pack/module that provides this subgraph
                            type: string
                    required:
                        - node_pack
                    type: object
                name:
                    description: Display name of the subgraph blueprint
                    type: string
                source:
                    description: Source type of the subgraph - "templates" for workflow templates or "custom_node" for custom node subgraphs
                    type: string
            required:
                - source
                - name
                - info
            type: object
        HistoryDetailEntry:
            description: History entry with full prompt data
            properties:
                meta:
                    additionalProperties: true
                    description: Metadata about the execution and nodes
                    type: object
                outputs:
                    additionalProperties: true
                    description: Output data from execution (generated images, files, etc.)
                    type: object
                prompt:
                    description: Full prompt execution data
                    properties:
                        extra_data:
                            additionalProperties: true
                            description: Additional execution data
                            type: object
                        outputs_to_execute:
                            description: Output nodes to execute
                            items:
                                type: string
                            type: array
                        priority:
                            description: Execution priority
                            format: double
                            type: number
                        prompt:
                            additionalProperties: true
                            description: The workflow nodes
                            type: object
                        prompt_id:
                            description: The prompt ID
                            type: string
                    type: object
                status:
                    additionalProperties: true
                    description: Execution status and timeline information
                    type: object
            type: object
        HistoryDetailResponse:
            additionalProperties:
                $ref: '#/components/schemas/HistoryDetailEntry'
            description: |
                Detailed execution history response for a specific prompt.
                Returns a dictionary with prompt_id as key and full history data as value.
            type: object
        HistoryEntry:
            description: History entry with prompt_id and execution data
            properties:
                create_time:
                    description: Job creation timestamp (Unix timestamp in milliseconds)
                    format: int64
                    type: integer
                meta:
                    additionalProperties: true
                    description: Metadata about the execution and nodes
                    type: object
                outputs:
                    additionalProperties: true
                    description: Output data from execution (generated images, files, etc.)
                    type: object
                prompt:
                    description: Filtered prompt execution data (lightweight format)
                    properties:
                        extra_data:
                            additionalProperties: true
                            description: Additional execution data (workflow removed from extra_pnginfo)
                            type: object
                        priority:
                            description: Execution priority
                            format: double
                            type: number
                        prompt_id:
                            description: The prompt ID
                            type: string
                    type: object
                prompt_id:
                    description: Unique identifier for this prompt execution
                    type: string
                status:
                    additionalProperties: true
                    description: Execution status and timeline information
                    type: object
                workflow_id:
                    description: UUID identifying the workflow graph definition
                    type: string
            required:
                - prompt_id
            type: object
        HistoryManageRequest:
            additionalProperties: false
            description: Request to manage history operations
            properties:
                clear:
                    description: If true, clear all history for the authenticated user
                    type: boolean
                delete:
                    description: Array of job IDs to delete from history
                    items:
                        type: string
                    type: array
            type: object
        HistoryResponse:
            description: |
                Execution history response with history array.
                Returns an object with a "history" key containing an array of history entries.
                Each entry includes prompt_id as a property along with execution data.
            properties:
                history:
                    description: Array of history entries ordered by creation time (newest first)
                    items:
                        $ref: '#/components/schemas/HistoryEntry'
                    type: array
            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:
                cancelled:
                    description: |
                        True when a cancel event was successfully dispatched by this call.
                        False when the job was already in a terminal or cancelling state,
                        in which case the call is a no-op (still 200 — idempotent).
                    type: boolean
            required:
                - cancelled
            type: object
        JobDetailResponse:
            description: Full job details including workflow and outputs
            properties:
                create_time:
                    description: Job creation timestamp (Unix timestamp in milliseconds)
                    format: int64
                    type: integer
                execution_end_time:
                    description: Workflow execution completion timestamp (Unix milliseconds, only present for terminal states)
                    format: int64
                    type: integer
                execution_error:
                    allOf:
                        - $ref: '#/components/schemas/ExecutionError'
                    description: Detailed execution error from ComfyUI (only for failed jobs with structured error data)
                execution_meta:
                    additionalProperties: true
                    description: Node-level execution metadata (only for terminal states)
                    type: object
                execution_start_time:
                    description: Workflow execution start timestamp (Unix milliseconds, only present once execution has started)
                    format: int64
                    type: integer
                execution_status:
                    additionalProperties: true
                    description: ComfyUI execution status and timeline (only for terminal states)
                    type: object
                id:
                    description: Unique job identifier
                    format: uuid
                    type: string
                outputs:
                    additionalProperties: true
                    description: Full outputs object from ComfyUI (only for terminal states)
                    type: object
                outputs_count:
                    description: Total number of output files (omitted for non-terminal states)
                    type: integer
                preview_output:
                    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:
                        - pending
                        - in_progress
                        - completed
                        - failed
                        - cancelled
                    type: string
                update_time:
                    description: Last update timestamp (Unix timestamp in milliseconds)
                    format: int64
                    type: integer
                user_id:
                    description: |
                        ID of the user that owns this job (see the `workspace_id`
                        description above for why this is always the caller's own id
                        on a successful response).
                    type: string
                workflow:
                    additionalProperties: true
                    description: |
                        Full ComfyUI workflow (10-100KB, omitted if not available).

                        Sensitive credentials are redacted before the response is returned:
                        `extra_data.api_key_comfy_org`, when present, is replaced with the
                        literal string `"[REDACTED]"`. The field is preserved (not removed)
                        so existence checks still pass, but the value is not usable.
                    type: object
                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)
                        response from this operation is only ever returned for the
                        caller's own job (see this operation's ownership-scoped
                        query), so this is always the caller's own workspace —
                        consumers that also need to correlate this job to its
                        live-progress broadcast channel (workspace+user scoped; see
                        the internal common/gateways/broadcast package) can use this
                        value directly rather than resolving their own identity a
                        second way.
                    type: string
            required:
                - id
                - status
                - create_time
                - update_time
            type: object
        JobEntry:
            description: Lightweight job data for list views (workflow and full outputs excluded)
            properties:
                create_time:
                    description: Job creation timestamp (Unix timestamp in milliseconds)
                    format: int64
                    type: integer
                execution_end_time:
                    description: Workflow execution completion timestamp (Unix milliseconds, only present for terminal states)
                    format: int64
                    type: integer
                execution_error:
                    allOf:
                        - $ref: '#/components/schemas/ExecutionError'
                    description: Detailed execution error from ComfyUI (only for failed jobs with structured error data)
                execution_start_time:
                    description: Workflow execution start timestamp (Unix milliseconds, only present for terminal states)
                    format: int64
                    type: integer
                id:
                    description: Unique job identifier
                    format: uuid
                    type: string
                outputs_count:
                    description: Total number of output files (omitted for non-terminal states)
                    type: integer
                preview_output:
                    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:
                        - pending
                        - in_progress
                        - completed
                        - failed
                        - cancelled
                    type: string
                workflow_id:
                    description: UUID identifying the workflow graph definition
                    type: string
            required:
                - id
                - 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:
                assigned_inference:
                    description: The inference instance assigned to this job (if any)
                    nullable: true
                    type: string
                created_at:
                    description: When the job was created
                    format: date-time
                    type: string
                error_message:
                    description: Error message if the job failed
                    nullable: true
                    type: string
                id:
                    description: The job ID
                    format: uuid
                    type: string
                last_state_update:
                    description: When the job status was last changed
                    format: date-time
                    type: string
                status:
                    description: Current job status
                    enum:
                        - waiting_to_dispatch
                        - pending
                        - in_progress
                        - completed
                        - error
                        - cancelled
                    type: string
                updated_at:
                    description: When the job was last updated
                    format: date-time
                    type: string
            required:
                - id
                - status
                - created_at
                - updated_at
            type: object
        JobsCancelRequest:
            additionalProperties: false
            description: Request to cancel multiple jobs by ID.
            properties:
                job_ids:
                    description: Job identifiers (UUIDs) to cancel.
                    items:
                        format: uuid
                        type: string
                    maxItems: 100
                    minItems: 1
                    type: array
            required:
                - job_ids
            type: object
        JobsCancelResponse:
            description: Response for POST /api/jobs/cancel.
            properties:
                cancelled:
                    description: |
                        Job IDs for which a cancel event was successfully dispatched by this
                        call. Jobs already in a terminal or cancelling state are idempotently
                        skipped and will not appear here.
                    items:
                        type: string
                    type: array
            required:
                - cancelled
            type: object
        JobsListResponse:
            description: Paginated list of jobs for the authenticated user.
            properties:
                jobs:
                    description: Array of jobs ordered by specified sort field
                    items:
                        $ref: '#/components/schemas/JobEntry'
                    type: array
                pagination:
                    $ref: '#/components/schemas/PaginationInfo'
            required:
                - jobs
                - pagination
            type: object
        ListAssetsResponse:
            description: Paginated list of assets belonging to the authenticated user.
            properties:
                assets:
                    description: List of assets matching the query
                    items:
                        $ref: '#/components/schemas/Asset'
                    type: array
                has_more:
                    description: Whether more assets are available beyond this page
                    type: boolean
                next_cursor:
                    description: |
                        Opaque cursor to pass as the `after` query parameter to fetch the
                        next page. Omitted from the response when there are no more results.
                    type: string
                total:
                    description: Total number of assets matching the filters
                    type: integer
            required:
                - assets
                - total
                - has_more
            type: object
        ListTagsResponse:
            description: Paginated list of available asset tags.
            properties:
                has_more:
                    description: Whether more tags are available
                    type: boolean
                tags:
                    description: List of tags
                    items:
                        $ref: '#/components/schemas/TagInfo'
                    type: array
                total:
                    description: Total number of tags
                    type: integer
            required:
                - tags
                - total
                - has_more
            type: object
        ModelFile:
            description: Represents a model file with metadata
            properties:
                name:
                    description: The filename of the model
                    example: model.safetensors
                    type: string
                pathIndex:
                    description: Index of the path where this model is located
                    example: 0
                    type: integer
            required:
                - name
                - pathIndex
            type: object
        ModelFolder:
            description: Represents a folder containing models
            properties:
                folders:
                    description: List of paths where models of this type are stored
                    example:
                        - checkpoints
                    items:
                        type: string
                    type: array
                name:
                    description: The name of the model folder
                    example: checkpoints
                    type: string
            required:
                - name
                - folders
            type: object
        NodeInfo:
            description: Metadata describing a single ComfyUI node type and its inputs/outputs.
            properties:
                api_node:
                    description: Whether this is an API node
                    type: boolean
                category:
                    description: Category of the node
                    type: string
                deprecated:
                    description: Whether the node is deprecated
                    type: boolean
                description:
                    description: Description of the node
                    type: string
                display_name:
                    description: Display name of the node
                    type: string
                experimental:
                    description: Whether the node is experimental
                    type: boolean
                input:
                    additionalProperties: true
                    description: Input specifications for the node
                    type: object
                input_order:
                    additionalProperties:
                        items:
                            type: string
                        type: array
                    description: Order of inputs for display
                    type: object
                name:
                    description: Internal name of the node
                    type: string
                output:
                    description: Output types of the node
                    items:
                        type: string
                    type: array
                output_is_list:
                    description: Whether each output is a list
                    items:
                        type: boolean
                    type: array
                output_name:
                    description: Names of the outputs
                    items:
                        type: string
                    type: array
                output_node:
                    description: Whether this is an output node
                    type: boolean
                output_tooltips:
                    description: Tooltips for outputs
                    items:
                        type: string
                    type: array
                python_module:
                    description: Python module implementing the node
                    type: string
            type: object
        PaginationInfo:
            description: |
                Pagination metadata included in list responses. Supports both legacy
                offset/limit pagination and cursor-based pagination. When cursor-based
                pagination is used, `next_cursor` is the primary pagination token and
                `offset`/`total` may be zero.
            properties:
                has_more:
                    description: Whether more items are available beyond this page
                    type: boolean
                limit:
                    description: Items per page
                    minimum: 1
                    type: integer
                next_cursor:
                    description: |
                        Opaque cursor for the next page. Pass this value as the `after`
                        query parameter on the next request. Empty or absent when there
                        are no more results.
                    type: string
                offset:
                    deprecated: true
                    description: 'Current offset (0-based). Deprecated: use cursor-based pagination.'
                    minimum: 0
                    type: integer
                total:
                    description: Total number of items matching filters (may be 0 when using cursor pagination)
                    minimum: 0
                    type: integer
            required:
                - offset
                - limit
                - total
                - has_more
            type: object
        PromptErrorResponse:
            additionalProperties: true
            description: Error response for ComfyUI prompt execution.
            type: object
        PromptInfo:
            description: Metadata about the currently running and queued prompts.
            properties:
                exec_info:
                    properties:
                        queue_remaining:
                            description: Number of items remaining in the queue
                            type: integer
                    type: object
            type: object
        PromptRequest:
            description: Request body for submitting a ComfyUI workflow prompt for execution.
            properties:
                extra_data:
                    additionalProperties: true
                    description: Extra data to be associated with the prompt
                    type: object
                front:
                    description: If true, adds the prompt to the front of the queue
                    type: boolean
                number:
                    description: Priority number for the queue (lower numbers have higher priority)
                    type: number
                partial_execution_targets:
                    description: List of node names to execute
                    items:
                        type: string
                    type: array
                prompt:
                    additionalProperties: true
                    description: The workflow graph to execute
                    type: object
                workflow_id:
                    description: UUID identifying the cloud workflow entity to associate with this job
                    type: string
                workflow_metadata:
                    additionalProperties:
                        type: string
                    description: 'Key/values echoed on the json websocket messages of this prompt that carry a `prompt_id`, so a client can tell which of its open workflows a message belongs to. Messages without a `prompt_id`, such as `status`, do not carry it, because a single socket serves every open workflow and such a message has no one owner. The server does not interpret the contents. Limited to 256 bytes serialised; a larger or non-object value is ignored. When this field is omitted, the server falls back to `{workflow_id: extra_data.extra_pnginfo.workflow.id}` if the submitted workflow carries an id, so a client that sends only the workflow gets the same messages. Note the `workflow_id` key a client typically sends here is the graph id from `extra_pnginfo.workflow.id`, which is not the same thing as the `workflow_id` field above.'
                    type: object
                workflow_version_id:
                    description: UUID identifying the workflow version to associate with this job
                    type: string
            required:
                - prompt
            type: object
        PromptResponse:
            description: Response returned after successfully queuing a workflow prompt.
            properties:
                node_errors:
                    additionalProperties: true
                    description: Any errors in the nodes of the prompt
                    type: object
                number:
                    description: Priority number in the queue
                    type: number
                prompt_id:
                    description: Unique identifier for the prompt execution
                    format: uuid
                    type: string
            type: object
        PublishWorkflowAssetsRequest:
            description: Request body for publishing workflow assets to the Hub.
            properties:
                asset_ids:
                    description: IDs of assets (inputs and models) to snapshot.
                    items:
                        type: string
                    type: array
            required:
                - asset_ids
            type: object
        PublishedWorkflowDetail:
            description: Full detail of a publicly published workflow on the Hub.
            properties:
                assets:
                    description: Published assets with their library status for the caller.
                    items:
                        $ref: '#/components/schemas/AssetInfo'
                    type: array
                listed:
                    type: boolean
                name:
                    description: Human-readable workflow name.
                    type: string
                publish_time:
                    format: date-time
                    nullable: true
                    type: string
                share_id:
                    type: string
                workflow_id:
                    type: string
                workflow_json:
                    additionalProperties: true
                    description: The workflow JSON content at publish time.
                    type: object
            required:
                - share_id
                - workflow_id
                - name
                - listed
                - workflow_json
                - assets
            type: object
        QueueInfo:
            description: Queue information with pending and running jobs
            properties:
                queue_pending:
                    description: Array of pending job items (ordered by creation time, oldest first)
                    items:
                        description: |
                            Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata]
                            - [0] job_number (integer): Position in queue (1-based)
                            - [1] prompt_id (string): Job UUID
                            - [2] workflow_json (object): Full ComfyUI workflow
                            - [3] output_node_ids (array): Node IDs to return results from
                            - [4] metadata (object): Contains {create_time: <milliseconds>}
                        items: {}
                        maxItems: 5
                        minItems: 5
                        type: array
                    type: array
                queue_running:
                    description: Array of currently running job items
                    items:
                        description: |
                            Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata]
                            - [0] job_number (integer): Position in queue (1-based)
                            - [1] prompt_id (string): Job UUID
                            - [2] workflow_json (object): Full ComfyUI workflow
                            - [3] output_node_ids (array): Node IDs to return results from
                            - [4] metadata (object): Contains {create_time: <milliseconds>}
                        items: {}
                        maxItems: 5
                        minItems: 5
                        type: array
                    type: array
            type: object
        QueueManageRequest:
            additionalProperties: false
            description: Request to manage queue operations
            properties:
                clear:
                    description: If true, clear all pending jobs from the queue
                    type: boolean
                delete:
                    description: Array of job IDs to cancel; pending and running jobs transition to cancelled
                    items:
                        type: string
                    type: array
            type: object
        QueueManageResponse:
            description: Response after a queue management action (delete or clear).
            properties:
                cleared:
                    description: Whether the queue was cleared
                    type: boolean
                deleted:
                    description: Array of job IDs that were successfully cancelled
                    items:
                        type: string
                    type: array
            type: object
        SystemStatsResponse:
            description: System statistics response
            properties:
                devices:
                    items:
                        properties:
                            name:
                                description: Device name
                                type: string
                            type:
                                description: Device type
                                type: string
                            vram_free:
                                description: Free VRAM in bytes
                                type: number
                            vram_total:
                                description: Total VRAM in bytes
                                type: number
                        required:
                            - name
                            - type
                        type: object
                    type: array
                system:
                    properties:
                        argv:
                            description: Command line arguments
                            items:
                                type: string
                            type: array
                        cloud_version:
                            description: Cloud ingest service version (commit hash)
                            type: string
                        comfyui_frontend_version:
                            description: ComfyUI frontend version (commit hash or tag)
                            type: string
                        comfyui_version:
                            description: ComfyUI version
                            type: string
                        deploy_environment:
                            description: How this ComfyUI instance is deployed (e.g. cloud, local-git, local-portable, local-desktop)
                            type: string
                        embedded_python:
                            description: Whether using embedded Python
                            type: boolean
                        os:
                            description: Operating system
                            type: string
                        python_version:
                            description: Python version
                            type: string
                        pytorch_version:
                            description: PyTorch version
                            type: string
                        ram_free:
                            description: Free RAM in bytes
                            type: number
                        ram_total:
                            description: Total RAM in bytes
                            type: number
                        workflow_templates_version:
                            description: Workflow templates version
                            type: string
                    required:
                        - os
                        - python_version
                        - embedded_python
                        - comfyui_version
                        - pytorch_version
                        - argv
                        - ram_total
                        - ram_free
                    type: object
            required:
                - system
                - devices
            type: object
        TagInfo:
            description: Metadata for a single tag that can be applied to assets.
            properties:
                count:
                    description: Number of assets using this tag
                    type: integer
                name:
                    description: Tag name
                    type: string
            required:
                - name
                - count
            type: object
        TagsModificationResponse:
            description: Response after adding, updating, or removing tags on an asset.
            properties:
                added:
                    description: Tags that were successfully added (for add operation)
                    items:
                        type: string
                    type: array
                already_present:
                    description: Tags that were already present (for add operation)
                    items:
                        type: string
                    type: array
                not_present:
                    description: Tags that were not present (for remove operation)
                    items:
                        type: string
                    type: array
                removed:
                    description: Tags that were successfully removed (for remove operation)
                    items:
                        type: string
                    type: array
                total_tags:
                    description: All tags on the asset after the operation
                    items:
                        type: string
                    type: array
            required:
                - total_tags
            type: object
        TaskEntry:
            description: Task data for list views
            properties:
                completed_at:
                    description: When task completed or failed (null if not finished)
                    format: date-time
                    type: string
                create_time:
                    description: Task creation timestamp
                    format: date-time
                    type: string
                id:
                    description: Unique task identifier
                    format: uuid
                    type: string
                started_at:
                    description: When task execution started (null if not started)
                    format: date-time
                    type: string
                status:
                    description: Current task status
                    enum:
                        - created
                        - running
                        - completed
                        - failed
                    type: string
                task_name:
                    description: Task type name (e.g., model_upload)
                    type: string
            required:
                - id
                - task_name
                - status
                - create_time
            type: object
        TaskResponse:
            description: Full task details including payload and result
            properties:
                completed_at:
                    description: When task completed or failed (null if not finished)
                    format: date-time
                    type: string
                create_time:
                    description: Task creation timestamp
                    format: date-time
                    type: string
                error_message:
                    description: Error message on failure (null if not failed)
                    type: string
                id:
                    description: Unique task identifier
                    format: uuid
                    type: string
                idempotency_key:
                    description: Caller-provided key for idempotent task creation
                    type: string
                payload:
                    additionalProperties: true
                    description: Task input data
                    type: object
                result:
                    additionalProperties: true
                    description: Task output data (null if not completed)
                    type: object
                started_at:
                    description: When task execution started (null if not started)
                    format: date-time
                    type: string
                status:
                    description: Current task status
                    enum:
                        - created
                        - running
                        - completed
                        - failed
                    type: string
                task_name:
                    description: Task type name (e.g., model_upload)
                    type: string
                update_time:
                    description: Task last update timestamp
                    format: date-time
                    type: string
            required:
                - id
                - idempotency_key
                - task_name
                - payload
                - status
                - create_time
                - update_time
            type: object
        TasksListResponse:
            description: Paginated list of background tasks for the authenticated user.
            properties:
                pagination:
                    $ref: '#/components/schemas/PaginationInfo'
                tasks:
                    description: Array of tasks ordered by create_time
                    items:
                        $ref: '#/components/schemas/TaskEntry'
                    type: array
            required:
                - tasks
                - pagination
            type: object
        UpdateWorkflowRequest:
            description: Request body for updating an existing saved workflow.
            properties:
                default_view:
                    description: New default view mode
                    enum:
                        - workflow
                        - app
                    type: string
                description:
                    description: New description
                    type: string
                name:
                    description: New display name
                    type: string
            type: object
        UserDataResponseFull:
            description: User data listing entry with file metadata (path, size, modification time).
            properties:
                modified:
                    description: UNIX timestamp of the last modification in milliseconds.
                    format: int64
                    type: integer
                path:
                    type: string
                size:
                    type: integer
            type: object
        UserResponse:
            description: User information response
            properties:
                id:
                    description: Firebase UID of the authenticated user
                    type: string
                status:
                    description: User status (always "active" for authenticated users)
                    type: string
            required:
                - id
                - status
            type: object
        WorkflowForkedFrom:
            description: Reference to the parent workflow from which this workflow was forked.
            properties:
                workflow_id:
                    type: string
                workflow_version_id:
                    type: string
            type: object
        WorkflowListResponse:
            description: Paginated list of saved workflows.
            properties:
                data:
                    items:
                        $ref: '#/components/schemas/WorkflowResponse'
                    type: array
                pagination:
                    $ref: '#/components/schemas/PaginationInfo'
            required:
                - data
                - pagination
            type: object
        WorkflowPublishInfo:
            description: Publishing metadata for a workflow shared to the Hub.
            properties:
                assets:
                    description: Published assets (inputs and models).
                    items:
                        $ref: '#/components/schemas/AssetInfo'
                    type: array
                listed:
                    type: boolean
                publish_time:
                    format: date-time
                    nullable: true
                    type: string
                share_id:
                    type: string
                workflow_id:
                    type: string
            required:
                - workflow_id
                - share_id
                - listed
                - assets
            type: object
        WorkflowResponse:
            description: Full workflow entity including metadata and version history.
            properties:
                created_at:
                    format: date-time
                    type: string
                created_by:
                    type: string
                default_view:
                    enum:
                        - workflow
                        - app
                    type: string
                description:
                    type: string
                forked_from:
                    $ref: '#/components/schemas/WorkflowForkedFrom'
                id:
                    type: string
                latest_version:
                    type: integer
                name:
                    type: string
                updated_at:
                    format: date-time
                    type: string
            required:
                - id
                - latest_version
                - created_by
                - created_at
                - updated_at
            type: object
        WorkflowVersionContentResponse:
            description: Full workflow version including the serialized workflow JSON.
            properties:
                created_at:
                    format: date-time
                    type: string
                created_by:
                    type: string
                dependency_asset_ids:
                    items:
                        type: string
                    type: array
                id:
                    type: string
                version:
                    type: integer
                workflow_json:
                    additionalProperties: true
                    type: object
            required:
                - id
                - version
                - workflow_json
                - created_by
                - created_at
            type: object
        WorkflowVersionResponse:
            description: Metadata for a single workflow version.
            properties:
                created_at:
                    format: date-time
                    type: string
                created_by:
                    type: string
                id:
                    type: string
                latest_version:
                    type: integer
                version:
                    type: integer
            required:
                - id
                - version
                - latest_version
                - created_by
                - created_at
            type: object
    securitySchemes:
        ApiKeyAuth:
            description: |
                API key authentication. Keys are prefixed with 'comfyui-' and can be
                generated from user account settings. Example: 'comfyui-abc123...'
            in: header
            name: X-API-Key
            type: apiKey
        BearerAuth:
            bearerFormat: JWT
            description: |
                Firebase JWT token authentication. Obtain a token by authenticating
                with Firebase and pass it in the Authorization header.
            scheme: bearer
            type: http
        CookieAuth:
            description: |
                Session cookie authentication. Set automatically after successful
                login via the /api/auth/session endpoint.
            in: cookie
            name: session
            type: apiKey
info:
    description: |
        API for ComfyUI - A powerful and modular UI for Stable Diffusion.

        This API allows you to interact with ComfyUI programmatically, including:
        - Retrieving prompt information
        - Retrieving node information
    license:
        name: GNU General Public License v3.0
        url: https://github.com/Comfy-Org/ComfyUI/blob/master/LICENSE
    title: ComfyUI API
    version: 1.0.0
openapi: 3.0.3
paths:
    /api/assets:
        get:
            description: |
                Retrieves a paginated list of assets belonging to the authenticated user.
                Supports filtering by tags, name, metadata, and sorting options.
            operationId: listAssets
            parameters:
                - deprecated: true
                  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
                  schema:
                    items:
                        type: string
                    type: array
                  style: form
                - deprecated: true
                  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
                  schema:
                    items:
                        type: string
                    type: array
                  style: form
                - 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
                  schema:
                    items:
                        type: string
                    type: array
                  style: form
                - 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
                  schema:
                    items:
                        type: string
                    type: array
                  style: form
                - 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
                  schema:
                    items:
                        type: string
                    type: array
                  style: form
                - description: Filter assets where name contains this substring (case-insensitive)
                  in: query
                  name: name_contains
                  schema:
                    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
                - description: Field to sort by
                  in: query
                  name: sort
                  schema:
                    default: created_at
                    enum:
                        - name
                        - created_at
                        - updated_at
                        - size
                        - last_access_time
                    type: string
                - description: Sort order
                  in: query
                  name: order
                  schema:
                    default: desc
                    enum:
                        - asc
                        - desc
                    type: string
                - description: Whether to include public/shared assets in results
                  in: query
                  name: include_public
                  schema:
                    default: true
                    type: boolean
                - description: |
                    Filter assets by content hash, in the canonical `blake3:<hex>`
                    form. Matches regardless of which of this asset store's two
                    internal hash storage formats the matching row was written
                    under (the canonical form used by from-hash-created references,
                    or the raw `<hex>.<ext>`/bare `<hex>` storage key used by direct
                    uploads) — both represent the same content hash.
                  in: query
                  name: hash
                  schema:
                    type: string
                - description: |
                    Opaque cursor for keyset pagination. Pass the `next_cursor` value
                    from the previous response to fetch the next page. When provided,
                    `offset` is ignored. Cursor pagination is only supported with
                    `sort` values `created_at`, `updated_at`, `name`, or `size`;
                    requests combining `after` with other sort fields return 400.
                    The cursor must have been minted under the same `sort` value used
                    in the follow-up request.
                  in: query
                  name: after
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListAssetsResponse'
                    description: Success - 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
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: List user assets
            tags:
                - file
        post:
            description: |
                Creates a new asset from a direct file upload (multipart/form-data) with associated metadata.

                If an asset with the same hash already exists, returns the existing asset.
            operationId: createAsset
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            properties:
                                file:
                                    description: The asset file to upload
                                    format: binary
                                    type: string
                                hash:
                                    description: Content hash of the file.
                                    pattern: ^(blake3|sha256):[a-f0-9]{64}$
                                    type: string
                                id:
                                    description: Optional asset ID for idempotent creation. If provided and asset exists, returns existing asset.
                                    format: uuid
                                    type: string
                                mime_type:
                                    description: MIME type of the asset (e.g., "image/png", "video/mp4")
                                    type: string
                                name:
                                    description: Display name for the asset
                                    type: string
                                preview_id:
                                    description: Optional preview asset ID. If not provided, images will use their own ID as preview.
                                    format: uuid
                                    type: string
                                tags:
                                    description: JSON-encoded array of freeform tag strings, e.g. '["models","checkpoint"]'. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.
                                    type: string
                                user_metadata:
                                    description: Custom JSON metadata as a string
                                    type: string
                            required:
                                - file
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AssetCreated'
                    description: |
                        Asset already existed for this user (deduplicated by content hash); the
                        existing asset is returned with created_new=false.
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AssetCreated'
                    description: Asset created successfully (created_new=true)
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request (bad file, invalid content type, etc.)
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: File too large
                "415":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unsupported media type
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Validation error (e.g., disallowed model_type tag)
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Create a new asset
            tags:
                - file
    /api/assets/{id}:
        delete:
            description: Deletes the asset record.
            operationId: deleteAsset
            parameters:
                - description: Asset ID
                  in: path
                  name: id
                  required: true
                  schema:
                    format: uuid
                    type: string
            responses:
                "204":
                    description: Asset record deleted successfully
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Asset not found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: 'Asset cannot be deleted because it is referenced by another resource, e.g. a workflow version (error code: ASSET_IN_USE)'
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Delete asset
            tags:
                - file
        get:
            description: Retrieves detailed information about a specific asset
            operationId: getAssetById
            parameters:
                - description: Asset ID
                  in: path
                  name: id
                  required: true
                  schema:
                    format: uuid
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/Asset'
                    description: Asset details retrieved successfully
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Asset not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Get asset details
            tags:
                - file
        put:
            description: |
                Updates an asset's metadata. At least one field must be provided.
                Only name, mime_type, preview_id, and user_metadata can be updated.
                For tag management, use POST (add) and DELETE (remove) /api/assets/{id}/tags.
            operationId: updateAsset
            parameters:
                - description: Asset ID
                  in: path
                  name: id
                  required: true
                  schema:
                    format: uuid
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            minProperties: 1
                            properties:
                                mime_type:
                                    description: Updated MIME type of the asset
                                    type: string
                                name:
                                    description: New display name for the asset
                                    type: string
                                preview_id:
                                    description: Updated preview asset ID
                                    format: uuid
                                    type: string
                                user_metadata:
                                    additionalProperties: true
                                    description: Updated custom metadata
                                    type: object
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AssetUpdated'
                    description: Asset updated successfully
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: |
                        Invalid request — no fields provided, or `preview_id` is the zero UUID
                        (`INVALID_PREVIEW_ID`).
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: |
                        Asset not found — returned both when the asset being updated does
                        not exist and when `preview_id` does not reference an asset
                        accessible to the caller.
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Update asset metadata
            tags:
                - file
    /api/assets/{id}/content:
        get:
            description: |
                Returns the binary content of an asset by ID.

                The contract is the same across runtimes — "GET this path and you
                receive the asset's bytes" — but the mechanism differs:
                - **Local ComfyUI** streams the bytes directly (`200`,
                  `application/octet-stream`).
                - **Cloud** does not proxy large files; it responds `302` with a
                  `Location` redirect to a short-lived signed storage URL. Clients that
                  follow redirects (browsers, `fetch`/XHR, `<img>`/`<video>`) receive
                  the bytes transparently.

                Prefer this over the filename-addressed `/api/view` when you have an
                asset ID.
            operationId: getAssetContent
            parameters:
                - description: Asset ID
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
                - description: |
                    Content-Disposition for the response: `attachment` (download) or
                    `inline` (render in browser). Defaults to `attachment`.
                  in: query
                  name: disposition
                  schema:
                    default: attachment
                    enum:
                        - inline
                        - attachment
                    type: string
            responses:
                "200":
                    content:
                        application/octet-stream:
                            schema:
                                format: binary
                                type: string
                    description: Asset content stream (local runtime streams the bytes directly)
                "302":
                    description: Redirect to a signed storage URL (cloud runtime)
                    headers:
                        Cache-Control:
                            description: Private caching directive scoped to the signed URL lifetime
                            schema:
                                type: string
                        Location:
                            description: Short-lived signed URL to the asset content in storage
                            schema:
                                type: string
                        Vary:
                            description: Partitions any cached redirect by auth credentials so a private redirect is not reused across users
                            schema:
                                type: string
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Asset not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            security:
                - ApiKeyAuth: []
                - BearerAuth: []
                - CookieAuth: []
            summary: Get asset content
            tags:
                - file
    /api/assets/{id}/tags:
        delete:
            description: Removes one or more tags from an existing asset
            operationId: removeAssetTags
            parameters:
                - description: Asset ID
                  in: path
                  name: id
                  required: true
                  schema:
                    format: uuid
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                tags:
                                    description: Tags to remove from the asset
                                    items:
                                        type: string
                                    minItems: 1
                                    type: array
                            required:
                                - tags
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TagsModificationResponse'
                    description: Tags removed successfully
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Asset not found
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Validation error (e.g., reserved tag)
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Remove tags from asset
            tags:
                - file
        post:
            description: Adds one or more tags to an existing asset
            operationId: addAssetTags
            parameters:
                - description: Asset ID
                  in: path
                  name: id
                  required: true
                  schema:
                    format: uuid
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                tags:
                                    description: Tags to add to the asset
                                    items:
                                        type: string
                                    minItems: 1
                                    type: array
                            required:
                                - tags
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TagsModificationResponse'
                    description: Tags added successfully
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Asset not found
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Validation error (e.g., reserved tag)
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Add tags to asset
            tags:
                - file
    /api/assets/from-hash:
        post:
            description: |
                Creates a new asset reference using an existing asset's hash.
                This avoids re-uploading the file content when the asset already exists in storage.
                The user can provide their own metadata and tags for the reference.
            operationId: createAssetFromHash
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                hash:
                                    description: 'Blake3 content hash of the existing asset (blake3: prefix)'
                                    pattern: ^blake3:[a-f0-9]{64}$
                                    type: string
                                mime_type:
                                    description: MIME type of the asset (e.g., "image/png", "video/mp4")
                                    type: string
                                name:
                                    description: Display name for the asset reference (optional)
                                    type: string
                                tags:
                                    description: Freeform tags for the asset. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.
                                    items:
                                        type: string
                                    minItems: 1
                                    type: array
                                user_metadata:
                                    additionalProperties: true
                                    description: Custom metadata for this asset reference
                                    type: object
                            required:
                                - hash
                                - tags
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AssetCreated'
                    description: |
                        Asset reference already existed for this user (deduplicated by content
                        hash); the existing asset is returned with created_new=false.
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AssetCreated'
                    description: Asset reference created successfully (created_new=true)
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request (bad hash format, invalid tags, etc.)
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Source asset with given hash not found
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Validation error (e.g., disallowed model_type tag)
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Create asset reference from existing hash
            tags:
                - file
    /api/assets/hash/{hash}:
        head:
            description: |
                Checks if an asset exists in the system by its blake3 hash.
                Returns 200 if the asset exists, 404 if it doesn't.
            operationId: checkAssetByHash
            parameters:
                - description: Blake3 hash of the asset in format 'blake3:hex_digest'
                  in: path
                  name: hash
                  required: true
                  schema:
                    example: blake3:a1b2c3d4e5f67890123456789012345678901234567890123456789012345678
                    pattern: ^blake3:[a-f0-9]{64}$
                    type: string
            responses:
                "200":
                    description: Asset exists
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid hash format
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    description: Asset not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Check if asset exists by hash
            tags:
                - file
    /api/assets/prune:
        post:
            description: Starts a background job that removes asset entries whose underlying content no longer exists on disk.
            operationId: pruneAssets
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    marked:
                                        description: Number of assets marked as missing
                                        type: integer
                                    status:
                                        description: '"completed", or "cancelled" when a cancel stopped the prune part way; the assets it marked before that stay marked'
                                        type: string
                                type: object
                    description: Prune result
            summary: Mark assets whose backing files no longer exist on disk
    /api/assets/seed:
        post:
            description: Starts a background job that scans configured directories and registers assets not yet in the asset database.
            operationId: seedAssets
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                roots:
                                    description: Root folder paths to scan (if omitted, scans all)
                                    items:
                                        type: string
                                    type: array
                            type: object
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    status:
                                        type: string
                                type: object
                    description: Seed started
            summary: Trigger asset scan/seed from filesystem
    /api/assets/seed/cancel:
        post:
            description: Requests cancellation of the currently-running asset seed job.
            operationId: cancelAssetSeed
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    status:
                                        type: string
                                type: object
                    description: Scan cancelled
            summary: Cancel an in-progress asset scan
    /api/assets/seed/status:
        get:
            description: Returns progress/status of the most recent asset seed job.
            operationId: getAssetSeedStatus
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties: true
                                description: Scan progress details (files scanned, total, status, etc.)
                                type: object
                    description: Scan progress
            summary: Get asset scan progress
    /api/assets/tags/refine:
        get:
            description: |
                Returns a histogram of tags appearing on assets matching the given filters.
                Useful for refining asset searches by showing available tags and their counts.
                Only returns tags with non-zero counts (tags that exist on matching assets).
            operationId: getAssetTagHistogram
            parameters:
                - deprecated: true
                  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
                  schema:
                    items:
                        type: string
                    type: array
                  style: form
                - deprecated: true
                  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
                  schema:
                    items:
                        type: string
                    type: array
                  style: form
                - 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
                  schema:
                    items:
                        type: string
                    type: array
                  style: form
                - 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
                  schema:
                    items:
                        type: string
                    type: array
                  style: form
                - 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
                  schema:
                    items:
                        type: string
                    type: array
                  style: form
                - description: Filter assets where name contains this substring (case-insensitive)
                  in: query
                  name: name_contains
                  schema:
                    type: string
                - description: Maximum number of tags to return (1-1000, default 100)
                  in: query
                  name: limit
                  schema:
                    default: 100
                    maximum: 1000
                    minimum: 1
                    type: integer
                - description: Whether to include public/shared assets in results
                  in: query
                  name: include_public
                  schema:
                    default: true
                    type: boolean
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/AssetTagHistogramResponse'
                    description: Success - Tag histogram 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
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            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/default_workflow:
        get:
            description: Returns the workflow the frontend loads when no other workflow is open.
            operationId: getDefaultWorkflow
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties: true
                                type: object
                    description: Default workflow JSON
            security: []
            summary: Get the default workflow
            tags:
                - workflow
    /api/embeddings:
        get:
            description: Returns the list of text-encoder embeddings available on disk.
            operationId: getEmbeddings
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                items:
                                    type: string
                                type: array
                    description: Embedding names
            summary: List available embedding names
    /api/experiment/models:
        get:
            description: |
                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}.
                The folder vocabulary is resolved per request from the caller's identity: where the
                model_type migration is active for that caller the names are model_type folder_names
                (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":
                    content:
                        application/json:
                            schema:
                                items:
                                    $ref: '#/components/schemas/ModelFolder'
                                type: array
                    description: Success - List of model folders
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            security:
                - ApiKeyAuth: []
                - BearerAuth: []
                - {}
            summary: Get available model folders
            tags:
                - file
    /api/experiment/models/{folder}:
        get:
            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
                  in: path
                  name: folder
                  required: true
                  schema:
                    example: checkpoints
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                items:
                                    $ref: '#/components/schemas/ModelFile'
                                type: array
                    description: Success - List of models in the folder
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Folder not found or no models in folder
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            security:
                - ApiKeyAuth: []
                - BearerAuth: []
                - {}
            summary: Get models in a specific folder
            tags:
                - file
    /api/extensions:
        get:
            description: |
                Returns the list of custom node web extension JS files available for
                loading by the ComfyUI frontend. Paths are relative to the web root
                (e.g. `/extensions/VHS.core.js`).
            operationId: getExtensions
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                description: URL paths (relative to web root) of available extension JS files
                                items:
                                    type: string
                                type: array
                    description: JSON array of extension file paths
            security: []
            summary: List custom node JS extensions
            tags:
                - node
    /api/features:
        get:
            description: Returns the server's feature capabilities
            operationId: getFeatures
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties: true
                                properties:
                                    free_tier_balance:
                                        description: Free-tier job allowance for an authenticated non-paid (FREE-tier) user in the rollout. Absent for paid users and unauthenticated requests. Synthesized from config before a grant row exists so a brand-new user still sees their full allowance.
                                        properties:
                                            allowance:
                                                description: Total free jobs granted for the current period
                                                type: integer
                                            remaining:
                                                description: Free jobs remaining (allowance - used, floored at 0)
                                                type: integer
                                            used:
                                                description: Free jobs consumed so far
                                                type: integer
                                        required:
                                            - allowance
                                            - used
                                            - remaining
                                        type: object
                                    max_upload_size:
                                        description: Maximum upload size in bytes
                                        type: integer
                                    supports_preview_metadata:
                                        description: Whether the server supports preview metadata
                                        type: boolean
                                type: object
                    description: Success
                    headers:
                        Cache-Control:
                            description: Short-lived private cache to deduplicate rapid-fire calls from the frontend
                            schema:
                                type: string
                        Vary:
                            description: Cache key includes auth headers so anonymous and authenticated responses are stored separately
                            schema:
                                type: string
            security:
                - ApiKeyAuth: []
                - BearerAuth: []
                - CookieAuth: []
                - {}
            summary: Get server feature flags
            tags:
                - node
    /api/feedback:
        post:
            description: Submit feedback about the ComfyUI service
            operationId: submitFeedback
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/FeedbackRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/FeedbackResponse'
                    description: Feedback submitted successfully
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Submit user feedback
            tags:
                - feedback
    /api/files/mask-layers:
        get:
            description: |
                Given a mask file (any of the 4 layers), returns all related mask layer files.
                This is used by the mask editor to load the paint, mask, and painted layers
                when reopening a previously edited mask.
            operationId: getMaskLayers
            parameters:
                - description: Hash filename of any mask layer file
                  in: query
                  name: filename
                  required: true
                  schema:
                    example: abc123def456.png
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    mask:
                                        description: Filename of the mask layer
                                        nullable: true
                                        type: string
                                    paint:
                                        description: Filename of the paint strokes layer
                                        nullable: true
                                        type: string
                                    painted:
                                        description: Filename of the painted image layer
                                        nullable: true
                                        type: string
                                    painted_masked:
                                        description: Filename of the final composite layer
                                        nullable: true
                                        type: string
                                type: object
                    description: Success - Related mask layers returned
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: File not found or not a mask file
            summary: Get related mask layer files
            tags:
                - file
    /api/free:
        post:
            description: Frees GPU memory by unloading models and/or freeing the resident model cache.
            operationId: freeMemory
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                free_memory:
                                    description: Run garbage collection and free cached memory
                                    type: boolean
                                unload_models:
                                    description: Unload all models from VRAM/RAM
                                    type: boolean
                            type: object
            responses:
                "200":
                    description: Memory freed
            summary: Free GPU memory and/or unload models
    /api/global_subgraphs:
        get:
            description: |
                Returns a list of globally available subgraph blueprints.
                These are pre-built workflow components that can be used as nodes.
                The data field contains a promise that resolves to the full subgraph JSON.
            operationId: getGlobalSubgraphs
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties:
                                    $ref: '#/components/schemas/GlobalSubgraphInfo'
                                type: object
                    description: Success - Map of subgraph IDs to their metadata
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            security: []
            summary: Get available subgraph blueprints
            tags:
                - workflow
    /api/global_subgraphs/{id}:
        get:
            description: Returns the full data for a specific subgraph blueprint by ID
            operationId: getGlobalSubgraph
            parameters:
                - description: The unique identifier of the subgraph blueprint
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GlobalSubgraphData'
                    description: Success - Full subgraph data
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Subgraph not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            security: []
            summary: Get a specific subgraph blueprint
            tags:
                - workflow
    /api/history:
        post:
            deprecated: true
            description: |
                **Deprecated.** Superseded by the job-management endpoints under
                `/api/jobs`. Planned for removal no earlier than a future major
                release; sunset timeline TBD.

                Clear all history for the authenticated user or delete specific job IDs.
                Supports clearing all history or deleting specific job IDs.
            operationId: manageHistory
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/HistoryManageRequest'
                required: true
            responses:
                "200":
                    description: Success - History management operation completed
                "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
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Manage execution history
            tags:
                - workflow
    /api/history_v2:
        get:
            deprecated: true
            description: |
                **Deprecated.** Superseded by `GET /api/jobs`, which returns the same
                execution records in a paginated, filterable format. Planned for removal
                no earlier than a future major release; sunset timeline TBD.

                Retrieve execution history for the authenticated user with pagination support.
                Returns a lightweight history format with filtered prompt data (workflow removed from extra_pnginfo).
            operationId: getHistory
            parameters:
                - description: Maximum number of items to return
                  in: query
                  name: max_items
                  schema:
                    type: integer
                - description: Starting position (default 0)
                  in: query
                  name: offset
                  schema:
                    default: 0
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/HistoryResponse'
                    description: Success - Execution history retrieved
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized - Authentication required
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Get execution history (v2)
            tags:
                - workflow
    /api/history_v2/{prompt_id}:
        get:
            deprecated: true
            description: |
                **Deprecated.** Superseded by `GET /api/jobs/{job_id}`, which returns
                the same execution record. Planned for removal no earlier than a future
                major release; sunset timeline TBD.

                Retrieve detailed execution history for a specific prompt ID.
                Returns full history data including complete prompt information.
            operationId: getHistoryForPrompt
            parameters:
                - description: The prompt ID to retrieve history for
                  in: path
                  name: prompt_id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/HistoryDetailResponse'
                    description: Success - History for prompt retrieved
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized - Authentication required
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Prompt not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Get history for specific prompt
            tags:
                - workflow
    /api/i18n:
        get:
            description: Returns translation file URLs contributed by custom nodes, keyed by locale.
            operationId: getI18n
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties: true
                                description: Nested map of locale to translation key-value pairs
                                type: object
                    description: Translation map
            summary: Get internationalisation translation strings
    /api/interrupt:
        post:
            deprecated: true
            description: |
                Deprecated. Prefer the jobs-namespace cancel endpoints:
                POST /api/jobs/{job_id}/cancel for a single job, or
                POST /api/jobs/cancel to cancel jobs by ID.

                Cancels the first active job for the authenticated user (the currently
                running job if there is one, otherwise the next pending job). Takes no
                body and cannot target a specific job — use the jobs-namespace endpoints
                for that.
            operationId: interruptJob
            responses:
                "200":
                    description: Success - first active job cancelled, or no active job found
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized - Authentication required
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Interrupt the first active job
            tags:
                - queue
    /api/job/{job_id}/status:
        get:
            deprecated: true
            description: |
                **Deprecated.** Superseded by `GET /api/jobs/{job_id}` (plural path).
                Clients should migrate; the endpoint is retained for backward
                compatibility but will be removed in a future release.
            operationId: getJobStatus
            parameters:
                - description: The unique ID of the job
                  in: path
                  name: job_id
                  required: true
                  schema:
                    format: uuid
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/JobStatusResponse'
                    description: Success - Job status returned
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Forbidden - job belongs to another user
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Job not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Get job status (deprecated)
            tags:
                - job
    /api/jobs:
        get:
            description: |
                Retrieve a paginated list of jobs for the authenticated user.
                Returns lightweight job data optimized for list views.
                Workflow and full outputs are excluded to reduce payload size.
            operationId: listJobs
            parameters:
                - description: Filter by one or more statuses (comma-separated). If not provided, returns all jobs.
                  example: pending,in_progress
                  in: query
                  name: status
                  schema:
                    type: string
                - description: Filter by workflow ID (exact match)
                  example: 550e8400-e29b-41d4-a716-446655440000
                  in: query
                  name: workflow_id
                  schema:
                    type: string
                - description: Filter by output media type (only applies to completed jobs with outputs)
                  example: image
                  in: query
                  name: output_type
                  schema:
                    enum:
                        - image
                        - video
                        - audio
                        - 3d
                    type: string
                - description: Field to sort by (create_time = when job was submitted, execution_time = how long workflow took to run)
                  example: execution_time
                  in: query
                  name: sort_by
                  schema:
                    default: create_time
                    enum:
                        - create_time
                        - execution_time
                    type: string
                - description: Sort direction (asc = ascending, desc = descending)
                  in: query
                  name: sort_order
                  schema:
                    default: desc
                    enum:
                        - asc
                        - desc
                    type: string
                - description: |
                    Opaque cursor for keyset pagination. Pass the `next_cursor` value
                    from a previous response to fetch the next page.
                    Cursor pagination is supported only when `sort_by=create_time`
                    (default). If `sort_by=execution_time`, `after` is ignored and
                    offset/limit pagination is used.
                    Cursors are opaque base64url payloads — clients should treat them
                    as strings and not parse the contents.
                  example: eyJzIjoiY3JlYXRlX3RpbWUiLCJ2IjoiMTcxNjIwMDAwMDAwMDAwMCIsImlkIjoiYTFiMmMzZDQtZTVmNi03YTg5LWIwYzEtZDJlM2Y0YTViNmM3In0
                  in: query
                  name: after
                  schema:
                    type: string
                - deprecated: true
                  description: 'Pagination offset (0-based). Deprecated: prefer cursor-based pagination via `after`.'
                  in: query
                  name: offset
                  schema:
                    default: 0
                    minimum: 0
                    type: integer
                - description: Maximum items per page (1-1000)
                  in: query
                  name: limit
                  schema:
                    default: 100
                    maximum: 1000
                    minimum: 1
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/JobsListResponse'
                    description: Success - Jobs retrieved
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad request (e.g. malformed pagination cursor).
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized - Authentication required
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: List jobs with pagination and filtering
            tags:
                - workflow
    /api/jobs/{job_id}:
        get:
            description: |
                Retrieve complete details for a specific job including workflow and outputs.
                Used for detail views, workflow re-execution, and debugging.
            operationId: getJobDetail
            parameters:
                - description: Job identifier (UUID)
                  in: path
                  name: job_id
                  required: true
                  schema:
                    format: uuid
                    type: string
                - description: |
                    When present, each output item in the response receives a `short_url` field containing a short link for that asset. Omit this parameter (the default) to receive a response identical to the no-param baseline. The value selects the link's lifetime and auth model: use `ephemeral_tool_chain` for short-lived (≤5 minute) machine-to-machine handoffs — these are public bearer links where the link ID itself is the credential, so anyone holding the link can resolve it (intended for pasting into an agent/MCP tool chain); use `default` for durable (30 day) human-revisitable links, which are owner-gated and resolvable only by the authenticated owner. Links are always minted under the authenticated request owner's identity; the auth model is selected by the server and is never settable by the caller.
                  in: query
                  name: short_link
                  schema:
                    enum:
                        - ephemeral_tool_chain
                        - default
                    type: string
                  x-runtime:
                    - cloud
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/JobDetailResponse'
                    description: Success - Job details retrieved
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized - Authentication required
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Forbidden - Job does not belong to user
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Job not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            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: |
                Cancel a specific job for the authenticated user.

                Idempotent: a job that is already in a terminal state (completed, failed,
                cancelled) or already cancelling is treated as a successful no-op and
                returns 200. Only truly missing or cross-user jobs return 404.
            operationId: cancelJob
            parameters:
                - description: Job identifier (UUID)
                  in: path
                  name: job_id
                  required: true
                  schema:
                    format: uuid
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/JobCancelResponse'
                    description: Success - Cancel request accepted (or job was already terminal)
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request - job_id is not a valid UUID (emitted by request validation before the handler runs)
                "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 for this user
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error - cancellation failed
            summary: Cancel a job
            tags:
                - workflow
    /api/jobs/cancel:
        post:
            description: |
                Cancel one or more jobs for the authenticated user in a single request.

                State-agnostic: cancels both pending and running jobs (both transition to
                the cancelled state via the same mechanism as the single-job endpoint).

                Idempotent per job: a job already in a terminal or cancelling state is a
                no-op and simply will not appear in the returned `cancelled` list.

                Fail-fast on unknown IDs: if any provided job ID does not exist for this
                user, the request returns 404 and no jobs are cancelled. This surfaces
                bad IDs to the caller rather than silently dropping them.

                This is the canonical batch-cancel endpoint. The delete operation on
                POST /api/queue is deprecated in favour of this.
            operationId: cancelJobs
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/JobsCancelRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/JobsCancelResponse'
                    description: Success - cancel requests dispatched (or jobs were already terminal)
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad Request - job_ids is missing, empty, exceeds the maximum count, or contains an invalid UUID
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized - Authentication required
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: One or more job IDs not found for this user (no jobs cancelled)
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error - cancellation failed
            summary: Cancel multiple jobs
            tags:
                - workflow
    /api/node_replacements:
        get:
            description: |
                Returns mappings of unsupported node class names to their cloud-installed replacements.
                Used by the frontend to offer "Quick Fix" when a workflow contains missing nodes.
            operationId: getNodeReplacements
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties: true
                                type: object
                    description: Success - Node replacement mappings
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            security: []
            summary: Get node replacement mappings
            tags:
                - node
    /api/object_info:
        get:
            description: Returns information about all available nodes
            operationId: getNodeInfo
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties:
                                    $ref: '#/components/schemas/NodeInfo'
                                type: object
                    description: Success
            summary: Get all node information
            tags:
                - node
    /api/prompt:
        get:
            description: Returns information about the current prompt in the execution queue
            operationId: getPromptInfo
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PromptInfo'
                    description: Success
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Get information about current prompt execution
            tags:
                - workflow
        post:
            description: |
                Submit a workflow to be executed by the backend.
                The workflow is a JSON object describing the nodes and their connections.
            operationId: executePrompt
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PromptRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PromptResponse'
                    description: Success - Prompt accepted
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PromptErrorResponse'
                    description: Invalid prompt
                "402":
                    content:
                        application/json:
                            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:
                            schema:
                                $ref: '#/components/schemas/PromptErrorResponse'
                    description: Workflow JSON too large
                "429":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PromptErrorResponse'
                    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:
                            schema:
                                $ref: '#/components/schemas/PromptErrorResponse'
                    description: Internal server error
                "503":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PromptErrorResponse'
                    description: Service unavailable
            summary: Submit a workflow for execution
            tags:
                - workflow
    /api/queue:
        get:
            description: Returns information about running and pending items in the queue
            operationId: getQueueInfo
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/QueueInfo'
                    description: Success
                "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
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request parameters
            summary: Get queue information
            tags:
                - queue
        post:
            deprecated: true
            description: |
                Deprecated. Prefer the jobs-namespace cancel endpoints:
                POST /api/jobs/cancel for cancelling jobs by ID, and
                POST /api/jobs/{job_id}/cancel for a single job.

                Cancel specific jobs by ID (the `delete` field) or clear all pending
                jobs in the queue (the `clear` field). Despite the `delete` naming, this
                does not delete anything — listed jobs transition to the cancelled state,
                and `delete` cancels both pending and running jobs (not pending-only as
                previously documented). Job-by-ID cancellation is superseded by
                POST /api/jobs/cancel; `clear` has no jobs-namespace replacement yet.
            operationId: manageQueue
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/QueueManageRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/QueueManageResponse'
                    description: Success
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request parameters
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Manage queue operations
            tags:
                - queue
    /api/settings:
        get:
            description: Returns all settings for the authenticated user
            operationId: getAllSettings
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties: true
                                description: User settings as key-value pairs
                                type: object
                    description: Success
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
            summary: Get all user settings
            tags:
                - settings
        post:
            description: Update multiple settings (merge with existing)
            operationId: updateMultipleSettings
            requestBody:
                content:
                    application/json:
                        schema:
                            additionalProperties: true
                            description: Settings to update as key-value pairs
                            type: object
                    text/plain:
                        schema:
                            description: JSON string of settings to update
                            type: string
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties: true
                                description: Updated user settings
                                type: object
                    description: Success
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
            summary: Update multiple settings
            tags:
                - settings
    /api/settings/{id}:
        get:
            description: Returns a specific setting value by its id
            operationId: getSettingById
            parameters:
                - description: Setting id to retrieve
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                description: Setting value response
                                properties:
                                    value:
                                        description: The setting value
                                type: object
                    description: Success
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Setting not found
            summary: Get a specific setting by id
            tags:
                - settings
        post:
            description: Update a specific setting by its id
            operationId: updateSettingById
            parameters:
                - description: Setting id to update
                  in: path
                  name: id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            description: New value for the setting
                    text/plain:
                        schema:
                            description: JSON string of the new setting value
                            type: string
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                description: Updated setting value response
                                properties:
                                    value:
                                        description: The updated setting value
                                type: object
                    description: Success
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
            summary: Update a specific setting by id
            tags:
                - settings
    /api/system_stats:
        get:
            description: Returns system statistics including ComfyUI version, device info, and system resources
            operationId: getSystemStats
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/SystemStatsResponse'
                    description: Success
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
            security: []
            summary: Get system statistics
            tags:
                - system
    /api/tags:
        get:
            description: |
                Retrieves a list of all tags used across assets.
                Includes usage counts and filtering options.
            operationId: listTags
            parameters:
                - description: Filter tags by prefix
                  in: query
                  name: prefix
                  schema:
                    type: string
                - description: Maximum number of tags to return (1-1000)
                  in: query
                  name: limit
                  schema:
                    default: 100
                    maximum: 1000
                    minimum: 1
                    type: integer
                - description: Number of tags to skip for pagination
                  in: query
                  name: offset
                  schema:
                    default: 0
                    minimum: 0
                    type: integer
                - description: Sort order for tags
                  in: query
                  name: order
                  schema:
                    default: count_desc
                    enum:
                        - count_desc
                        - name_asc
                    type: string
                - description: Include tags with zero usage count
                  in: query
                  name: include_zero
                  schema:
                    default: false
                    type: boolean
                - description: Whether to include public/shared assets when counting tags
                  in: query
                  name: include_public
                  schema:
                    default: true
                    type: boolean
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ListTagsResponse'
                    description: Tags retrieved successfully
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request parameters
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: List all tags
            tags:
                - file
    /api/tasks:
        get:
            description: |
                Retrieve a paginated list of background tasks for the authenticated user.
                Supports filtering by task type, status, and creation time.
            operationId: listTasks
            parameters:
                - description: Filter by task type name (exact match)
                  example: model_upload
                  in: query
                  name: task_name
                  schema:
                    type: string
                - description: Filter by idempotency key (exact match). For best performance, specify task_name as well.
                  example: upload-model-abc123
                  in: query
                  name: idempotency_key
                  schema:
                    type: string
                - description: Filter by one or more statuses (comma-separated)
                  example: created,running
                  in: query
                  name: status
                  schema:
                    type: string
                - description: Filter tasks created after this timestamp (RFC3339 format)
                  example: "2024-01-01T00:00:00Z"
                  in: query
                  name: created_after
                  schema:
                    format: date-time
                    type: string
                - description: Filter tasks created before this timestamp (RFC3339 format)
                  example: "2024-12-31T23:59:59Z"
                  in: query
                  name: created_before
                  schema:
                    format: date-time
                    type: string
                - description: Sort direction (asc = ascending, desc = descending by create_time)
                  in: query
                  name: sort_order
                  schema:
                    default: desc
                    enum:
                        - asc
                        - desc
                    type: string
                - description: Pagination offset (0-based)
                  in: query
                  name: offset
                  schema:
                    default: 0
                    minimum: 0
                    type: integer
                - description: Maximum items per page (1-100)
                  in: query
                  name: limit
                  schema:
                    default: 20
                    maximum: 100
                    minimum: 1
                    type: integer
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TasksListResponse'
                    description: Success - Tasks retrieved
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized - Authentication required
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Validation error - Invalid filter values
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: List background tasks
            tags:
                - task
    /api/tasks/{task_id}:
        get:
            description: |
                Retrieve full details for a specific background task.
            operationId: getTask
            parameters:
                - description: Task identifier (UUID)
                  in: path
                  name: task_id
                  required: true
                  schema:
                    format: uuid
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/TaskResponse'
                    description: Success - Task details retrieved
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized - Authentication required
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Task not found (also returned for ownership failures to avoid leaking task existence)
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Get task details
            tags:
                - task
    /api/upload/image:
        post:
            description: |
                Upload an image file to cloud storage.

                Image limits:
                  - Maximum file size: 50 MB
                  - Maximum width/height per edge: 16384 px
                  - Maximum total pixel count: 64 megapixels (67108864 pixels)

                Uploads that exceed any of these limits are rejected with HTTP 400.
            operationId: uploadImage
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            properties:
                                image:
                                    description: The image file to upload
                                    format: binary
                                    type: string
                                overwrite:
                                    description: Whether to overwrite existing file (true/false)
                                    type: string
                                subfolder:
                                    description: Optional subfolder path
                                    type: string
                                type:
                                    description: Upload type (defaults to "output")
                                    type: string
                            required:
                                - image
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    name:
                                        description: Filename of the uploaded image
                                        type: string
                                    subfolder:
                                        description: Subfolder path where image was saved
                                        type: string
                                    type:
                                        description: Type of upload (e.g., "output")
                                        type: string
                                type: object
                    description: Image uploaded successfully
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Upload an image file
            tags:
                - file
    /api/upload/mask:
        post:
            description: |
                Upload a mask image to be applied to an existing image.

                Image limits apply to both the uploaded mask and the referenced
                original image:
                  - Maximum file size: 50 MB
                  - Maximum width/height per edge: 16384 px
                  - Maximum total pixel count: 64 megapixels (67108864 pixels)

                Uploads that exceed any of these limits are rejected with HTTP 400.
            operationId: uploadMask
            requestBody:
                content:
                    multipart/form-data:
                        schema:
                            properties:
                                image:
                                    description: The mask image file to upload
                                    format: binary
                                    type: string
                                original_ref:
                                    description: JSON string containing reference to the original image
                                    type: string
                            required:
                                - image
                                - original_ref
                            type: object
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    name:
                                        description: Filename of the uploaded mask
                                        type: string
                                    subfolder:
                                        description: Subfolder path where mask was saved
                                        type: string
                                    type:
                                        description: Type of upload (e.g., "output")
                                        type: string
                                type: object
                    description: Mask uploaded successfully
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Upload a mask image
            tags:
                - file
    /api/user:
        get:
            description: Returns information about the currently authenticated user
            operationId: getUser
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UserResponse'
                    description: Success
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
            summary: Get current user information
            tags:
                - user
    /api/userdata:
        get:
            description: Returns a list of user data files in the specified directory, optionally recursively and with full metadata.
            operationId: getUserdata
            parameters:
                - description: The directory to list files from.
                  in: query
                  name: dir
                  schema:
                    type: string
                - description: Whether to list files recursively.
                  in: query
                  name: recurse
                  schema:
                    default: false
                    type: boolean
                - description: Whether to split file information by type.
                  in: query
                  name: split
                  schema:
                    default: false
                    type: boolean
                - description: Whether to return full file metadata.
                  in: query
                  name: full_info
                  schema:
                    default: false
                    type: boolean
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/GetUserDataResponseFull'
                    description: A list of user data files.
                "400":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Bad request (e.g., invalid filename).
                "401":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Unauthorized.
                "404":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: File not found or invalid path.
                "500":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: General error
            summary: List user data files
            tags:
                - user
    /api/userdata/{file}:
        delete:
            description: |
                Delete a user data file from the database. The file parameter should be
                the relative path within the user's data directory.
            operationId: deleteUserdataFile
            parameters:
                - description: The file path to delete (URL encoded if necessary).
                  in: path
                  name: file
                  required: true
                  schema:
                    type: string
            responses:
                "204":
                    description: File deleted successfully (No Content).
                "401":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Unauthorized.
                "404":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: File not found.
                "500":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Internal server error.
            summary: Delete a user data file
            tags:
                - user
        get:
            description: Returns the requested user data file if it exists.
            operationId: getUserdataFile
            parameters:
                - description: The filename of the user data to retrieve.
                  in: path
                  name: file
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/octet-stream:
                            schema:
                                format: binary
                                type: string
                    description: Successfully retrieved the file.
                "400":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Bad request (e.g., invalid filename).
                "401":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Unauthorized.
                "404":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: File not found or invalid path.
                "500":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: General error
            summary: Get user data file
            tags:
                - user
        post:
            description: |
                Upload a file to a user's data directory. Optional query parameters allow
                control over overwrite behavior and response detail.
            operationId: postUserdataFile
            parameters:
                - description: The target file path (URL encoded if necessary).
                  in: path
                  name: file
                  required: true
                  schema:
                    type: string
                - description: If "false", prevents overwriting existing files. Defaults to "true".
                  in: query
                  name: overwrite
                  schema:
                    default: "true"
                    enum:
                        - "true"
                        - "false"
                    type: string
                - description: If "true", returns detailed file info; if "false", returns only the relative path.
                  in: query
                  name: full_info
                  schema:
                    default: "false"
                    enum:
                        - "true"
                        - "false"
                    type: string
            requestBody:
                content:
                    application/octet-stream:
                        schema:
                            format: binary
                            type: string
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UserDataResponseFull'
                    description: File uploaded successfully.
                "400":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Missing or invalid 'file' parameter.
                "401":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Unauthorized.
                "403":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: The requested path is not allowed.
                "409":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: File already exists and overwrite is set to false.
                "500":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: General error
            summary: Upload or update a user data file
            tags:
                - user
    /api/userdata/{file}/move/{dest}:
        post:
            description: |
                Move or rename a file within a user's data directory, with options for
                controlling overwrite behavior and response format.
            operationId: moveUserdataFile
            parameters:
                - description: The source file path (URL encoded if necessary).
                  in: path
                  name: file
                  required: true
                  schema:
                    type: string
                - description: The destination file path (URL encoded if necessary).
                  in: path
                  name: dest
                  required: true
                  schema:
                    type: string
                - description: If "false", prevents overwriting existing files. Defaults to "true".
                  in: query
                  name: overwrite
                  schema:
                    default: "true"
                    enum:
                        - "true"
                        - "false"
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/UserDataResponseFull'
                    description: File moved successfully.
                "400":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Missing or invalid parameters.
                "401":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Unauthorized.
                "404":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Source file not found.
                "409":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Destination file already exists and overwrite is set to false.
                "500":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: General error
            summary: Move or rename a user data file
            tags:
                - user
    /api/userdata/{file}/publish:
        get:
            description: Returns the publish status and share info for a workflow identified by its userdata path.
            operationId: getUserdataFilePublish
            parameters:
                - description: The workflow file path within the user's data directory (URL encoded if necessary).
                  in: path
                  name: file
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowPublishInfo'
                    description: Publish info (publish_time is null if never published)
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Workflow not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Get publish info for a workflow file
            tags:
                - workflows
        post:
            description: Creates a new published_workflow record from the latest version and snapshots the provided assets.
            operationId: postUserdataFilePublish
            parameters:
                - description: The workflow file path within the user's data directory (URL encoded if necessary).
                  in: path
                  name: file
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/PublishWorkflowAssetsRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowPublishInfo'
                    description: Workflow published
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Bad request
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Workflow not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Publish a workflow file
            tags:
                - workflows
    /api/users:
        get:
            description: |
                ComfyUI legacy users endpoint. Returns information about how user
                data is stored. In cloud this is always server-managed, so callers
                receive a constant response indicating server-side storage.
            operationId: getUsersInfo
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    migrated:
                                        description: Whether user data has been migrated (always true in cloud)
                                        type: boolean
                                    storage:
                                        description: Where user data is stored (always "server" in cloud)
                                        type: string
                                required:
                                    - storage
                                    - migrated
                                type: object
                    description: Userdata storage information
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
            summary: ComfyUI userdata storage info
            tags:
                - user
    /api/vhs/queryvideo:
        get:
            description: |
                VHS custom node endpoint that returns metadata about a video file
                (frame count, fps, resolution, duration). Currently returns default
                placeholder values; real ffprobe integration is a follow-up.
            operationId: getVhsQueryVideo
            parameters:
                - description: Name of the video file to query
                  in: query
                  name: filename
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    source:
                                        description: Source video metadata
                                        properties:
                                            duration:
                                                description: Duration in seconds
                                                type: number
                                            fps:
                                                description: Frames per second
                                                type: number
                                            frames:
                                                description: Total frame count
                                                type: integer
                                            size:
                                                description: '[width, height] in pixels'
                                                items:
                                                    type: integer
                                                maxItems: 2
                                                minItems: 2
                                                type: array
                                        required:
                                            - size
                                            - fps
                                            - frames
                                            - duration
                                        type: object
                                required:
                                    - source
                                type: object
                    description: Video metadata
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: |
                        Missing required query parameter. Produced by the oapi-codegen
                        wrapper via echo.NewHTTPError; the custom Echo HTTPErrorHandler
                        normalizes it to the standard ErrorResponse {code, message} shape
                        (BE-1178).
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
            security:
                - ApiKeyAuth: []
                - BearerAuth: []
                - CookieAuth: []
            summary: Query VHS video metadata
            tags:
                - file
    /api/view:
        get:
            description: |
                Retrieve and view a file from the ComfyUI file system.
                This endpoint is typically used to view generated images or other output files.
                Cookie auth is allowed on this endpoint because it's used by img/video tags in browsers.
            operationId: viewFile
            parameters:
                - description: Name of the file to view
                  in: query
                  name: filename
                  required: true
                  schema:
                    example: ComfyUI_00004_.png
                    type: string
                - description: Subfolder path where the file is located
                  in: query
                  name: subfolder
                  schema:
                    example: tests/foo/bar
                    type: string
                - description: Type of file (e.g., output, input, temp)
                  in: query
                  name: type
                  schema:
                    example: output
                    type: string
                - description: Full path to the file (used for temp files)
                  in: query
                  name: fullpath
                  schema:
                    type: string
                - description: Format of the file
                  in: query
                  name: format
                  schema:
                    type: string
                - description: Frame rate for video files
                  in: query
                  name: frame_rate
                  schema:
                    type: integer
                - description: Workflow identifier
                  in: query
                  name: workflow
                  schema:
                    type: string
                - description: Timestamp parameter
                  in: query
                  name: timestamp
                  schema:
                    example: 1234567890
                    type: integer
                - description: |
                    Image channel to extract from PNG images.
                    - 'rgb': Return only RGB channels (alpha set to fully opaque)
                    - 'a' or 'alpha': Return alpha channel as grayscale image
                    - If not specified, return original image unchanged via redirect
                  in: query
                  name: channel
                  schema:
                    example: rgb
                    type: string
                - description: |
                    Maximum dimension (width or height) to resize the image to, preserving aspect ratio.
                    The image is fit within a res x res box. Returns a JPEG thumbnail.
                    Only applies to raster image files (PNG, JPEG, WebP, GIF).
                  in: query
                  name: res
                  schema:
                    example: 256
                    maximum: 1024
                    minimum: 64
                    type: integer
            responses:
                "200":
                    content:
                        image/jpeg:
                            schema:
                                description: Resized JPEG thumbnail (returned when res parameter is used)
                                format: binary
                                type: string
                        image/png:
                            schema:
                                description: Processed PNG image with extracted channel
                                format: binary
                                type: string
                    description: Success - File content returned (used when channel or res parameter is present)
                "302":
                    description: Redirect to GCS signed URL
                    headers:
                        Cache-Control:
                            description: Cache directive for the redirect response
                            schema:
                                type: string
                        Location:
                            description: Signed URL to access the file in GCS
                            schema:
                                type: string
                        Vary:
                            description: Headers that affect response caching
                            schema:
                                type: string
                "400":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Invalid request parameters
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: File not found or unauthorized
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            security:
                - ApiKeyAuth: []
                - BearerAuth: []
                - CookieAuth: []
            summary: View a file
            tags:
                - file
    /api/workflow_templates:
        get:
            description: Returns available workflow templates
            operationId: getWorkflowTemplates
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                description: Empty object for workflow templates
                                type: object
                    description: Success
            security: []
            summary: Get available workflow templates
            tags:
                - workflow
    /api/workflows:
        get:
            description: Returns a paginated list of workflows for the authenticated user in the current workspace.
            operationId: listWorkflows
            parameters:
                - in: query
                  name: limit
                  schema:
                    default: 20
                    maximum: 100
                    type: integer
                - in: query
                  name: offset
                  schema:
                    default: 0
                    type: integer
                - description: Search workflows by name (case-insensitive substring match)
                  in: query
                  name: name
                  schema:
                    type: string
                - description: Filter by default view type
                  in: query
                  name: default_view
                  schema:
                    enum:
                        - workflow
                        - app
                    type: string
                - description: Sort field
                  in: query
                  name: sort
                  schema:
                    default: create_time
                    enum:
                        - create_time
                        - update_time
                        - name
                    type: string
                - description: Sort order
                  in: query
                  name: order
                  schema:
                    default: desc
                    enum:
                        - asc
                        - desc
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowListResponse'
                    description: Success
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: List workflows
            tags:
                - workflows
        post:
            description: Creates a new workflow with its first version.
            operationId: createWorkflow
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateWorkflowRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowResponse'
                    description: Workflow created successfully
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Validation error
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Create a new workflow
            tags:
                - workflows
    /api/workflows/{workflow_id}:
        delete:
            description: Soft-deletes a workflow.
            operationId: deleteWorkflow
            parameters:
                - description: The UUID of the workflow to delete.
                  in: path
                  name: workflow_id
                  required: true
                  schema:
                    type: string
            responses:
                "204":
                    description: Workflow deleted successfully
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Workflow not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Delete workflow
            tags:
                - workflows
        get:
            description: Retrieves workflow metadata by ID.
            operationId: getWorkflow
            parameters:
                - description: The UUID of the workflow.
                  in: path
                  name: workflow_id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowResponse'
                    description: Success
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Forbidden
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Workflow not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Get workflow
            tags:
                - workflows
        patch:
            description: Updates mutable workflow metadata (name, description, default_view).
            operationId: updateWorkflow
            parameters:
                - description: The UUID of the workflow to update.
                  in: path
                  name: workflow_id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/UpdateWorkflowRequest'
                required: true
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowResponse'
                    description: Success
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Workflow not found
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Validation error
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Update workflow metadata
            tags:
                - workflows
    /api/workflows/{workflow_id}/content:
        get:
            description: Retrieves the latest version of a workflow and its JSON content.
            operationId: getWorkflowContent
            parameters:
                - description: The UUID of the workflow whose content should be retrieved.
                  in: path
                  name: workflow_id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowVersionContentResponse'
                    description: Success
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Forbidden
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Workflow not found
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Get workflow content
            tags:
                - workflows
    /api/workflows/{workflow_id}/fork:
        post:
            description: Creates a new workflow by forking from an existing version.
            operationId: forkWorkflow
            parameters:
                - description: The UUID of the source workflow to fork from.
                  in: path
                  name: workflow_id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/ForkWorkflowRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowResponse'
                    description: Workflow forked successfully
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Forbidden
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Source workflow or version not found
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Validation error
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Fork a workflow
            tags:
                - workflows
    /api/workflows/{workflow_id}/versions:
        post:
            description: Creates a new workflow version with updated workflow JSON. Uses optimistic concurrency via base_version.
            operationId: createWorkflowVersion
            parameters:
                - description: The UUID of the workflow to create a new version for.
                  in: path
                  name: workflow_id
                  required: true
                  schema:
                    type: string
            requestBody:
                content:
                    application/json:
                        schema:
                            $ref: '#/components/schemas/CreateWorkflowVersionRequest'
                required: true
            responses:
                "201":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/WorkflowVersionResponse'
                    description: Version created successfully
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "403":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Forbidden - not the workflow owner
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Workflow not found
                "409":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Version conflict - base_version does not match latest
                "422":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Validation error
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Create a new version
            tags:
                - workflows
    /api/workflows/published/{share_id}:
        get:
            description: |
                Returns the published workflow details including the status of each
                published asset relative to the caller's library. Authentication is required.
            operationId: getPublishedWorkflow
            parameters:
                - description: The share ID of the published workflow.
                  in: path
                  name: share_id
                  required: true
                  schema:
                    type: string
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/PublishedWorkflowDetail'
                    description: Published workflow details with asset statuses
                "401":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Unauthorized
                "404":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Share not found
                "413":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Workflow JSON too large
                "500":
                    content:
                        application/json:
                            schema:
                                $ref: '#/components/schemas/ErrorResponse'
                    description: Internal server error
            summary: Get a published workflow by share ID
            tags:
                - workflows
    /health:
        get:
            description: |
                Returns `200 OK` if the database is reachable and dynamic config has
                loaded, otherwise `503 Service Unavailable`. Used by the GKE ingress
                for health checks. Response body is plain text for probe simplicity.
            operationId: getHealth
            responses:
                "200":
                    content:
                        text/plain:
                            schema:
                                example: OK
                                type: string
                    description: Service is healthy
                "503":
                    content:
                        text/plain:
                            schema:
                                example: Service Unavailable
                                type: string
                    description: Service is unhealthy
            security: []
            summary: Health probe for Kubernetes readiness/liveness
            tags:
                - system
    /internal/folder_paths:
        get:
            description: Returns the filesystem paths ComfyUI loads models and assets from, keyed by folder type.
            operationId: getInternalFolderPaths
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                additionalProperties:
                                    items:
                                        items:
                                            type: string
                                        type: array
                                    type: array
                                description: Map of folder type name to list of path entries
                                type: object
                    description: Dictionary of folder type to paths
            summary: Get configured folder paths
    /internal/logs:
        get:
            description: Returns ComfyUI log entries from the in-memory log buffer.
            operationId: getInternalLogs
            responses:
                "200":
                    content:
                        text/plain:
                            schema:
                                type: string
                    description: Log text
            summary: Get server logs as text
    /internal/logs/raw:
        get:
            description: Returns the raw ComfyUI log buffer plus size metadata.
            operationId: getInternalLogsRaw
            responses:
                "200":
                    content:
                        application/json:
                            schema:
                                properties:
                                    entries:
                                        items:
                                            properties:
                                                m:
                                                    description: Message
                                                    type: string
                                                t:
                                                    description: Timestamp
                                                    type: number
                                            type: object
                                        type: array
                                    size:
                                        properties:
                                            cols:
                                                type: integer
                                            rows:
                                                type: integer
                                        type: object
                                type: object
                    description: Structured log data
            summary: Get raw structured log entries
    /internal/logs/subscribe:
        patch:
            description: Subscribes or unsubscribes the current client from live log streaming over the WebSocket.
            operationId: subscribeToLogs
            requestBody:
                content:
                    application/json:
                        schema:
                            properties:
                                clientId:
                                    description: WebSocket client ID
                                    type: string
                                enabled:
                                    description: Enable or disable log streaming for this client
                                    type: boolean
                            required:
                                - clientId
                                - enabled
                            type: object
                required: true
            responses:
                "200":
                    description: Subscription updated
            summary: Subscribe or unsubscribe a WebSocket client to log streaming
security:
    - ApiKeyAuth: []
    - BearerAuth: []
servers:
    - description: Default ComfyUI server
      url: /
tags:
    - description: Workflow execution and management
      name: workflow
    - description: Node information
      name: node
    - description: File operations
      name: file
    - description: User settings management
      name: settings
    - description: User feedback management
      name: feedback
    - description: System operations and monitoring
      name: system
    - description: User information and management
      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
      name: queue
    - description: Job lifecycle queries
      name: job