openapi.yaml

openapi: 3.1.0
info:
  title: ComfyUI API
  description: |
    API for ComfyUI - A powerful and modular stable diffusion GUI and backend.

    This API allows you to interact with ComfyUI programmatically, including:
    - Submitting and managing workflow executions
    - Querying node/object information
    - Uploading and viewing files
    - Managing user settings and data
    - Asset management (feature-gated)

    ## Dual-path routing
    Every route registered via `self.routes` in the ComfyUI server is available at
    both its bare path (e.g. `/prompt`) and an `/api`-prefixed path (e.g. `/api/prompt`).
    This spec uses the `/api`-prefixed versions as canonical.

    ## Multi-user mode
    When ComfyUI is started with `--multi-user`, the `Comfy-User` header identifies
    the active user for settings, userdata, and history isolation. This is **not** a
    security mechanism — it is an organisational convenience with no authentication
    or authorisation behind it.
  version: 1.0.0
  license:
    name: GNU General Public License v3.0
    url: https://github.com/comfyanonymous/ComfyUI/blob/master/LICENSE

servers:
  - url: /
    description: Default ComfyUI server (typically http://127.0.0.1:8188)

tags:
  - name: prompt
    description: Workflow submission and prompt info
  - name: queue
    description: Queue inspection and management
  - name: history
    description: Execution history
  - name: upload
    description: File upload endpoints
  - name: view
    description: File viewing / download
  - name: system
    description: System stats and feature flags
  - name: node
    description: Node / object_info definitions
  - name: model
    description: Model folder and file listing
  - name: user
    description: User management (multi-user mode)
  - name: userdata
    description: Per-user file storage
  - name: settings
    description: Per-user settings
  - name: extensions
    description: Frontend extension JS files
  - name: subgraph
    description: Global subgraph blueprints
  - name: internal
    description: Internal / debug endpoints
  - name: assets
    description: Asset management (feature-gated behind enable-assets)

  - name: auth
    description: Authentication and session management (cloud-only)
  - name: billing
    description: Billing, subscriptions, and payment management (cloud-only)
  - name: workspace
    description: Workspace and team management (cloud-only)
  - name: hub
    description: "ComfyUI Hub: profiles, shared workflows, and labels (cloud-only)"
  - name: workflows
    description: Cloud workflow management and versioning (cloud-only)
  - name: task
    description: Background task management (cloud-only)
  - name: runtime-only
    description: Operations served exclusively by the cloud runtime with no local equivalent

paths:
  # ---------------------------------------------------------------------------
  # WebSocket
  # ---------------------------------------------------------------------------
  /ws:
    get:
      operationId: connectWebSocket
      tags: [system]
      summary: WebSocket connection for real-time updates
      description: |
        Upgrades to a WebSocket connection that streams execution progress,
        node status, and output messages. The server sends an initial `status`
        message with the session ID (SID) on connect.

        ## Message types (server → client)
        The server sends JSON messages with a `type` field. See the
        `x-websocket-messages` list below for the schema of each message type.
      parameters:
        - name: clientId
          in: query
          required: false
          schema:
            type: string
          description: Client identifier. If omitted the server assigns one.
      responses:
        "101":
          description: WebSocket upgrade successful
      x-websocket-messages:
        - type: status
          schema:
            $ref: "#/components/schemas/StatusWsMessage"
        - type: progress
          schema:
            $ref: "#/components/schemas/ProgressWsMessage"
        - type: progress_text
          schema:
            $ref: "#/components/schemas/ProgressTextWsMessage"
        - type: progress_state
          schema:
            $ref: "#/components/schemas/ProgressStateWsMessage"
        - type: executing
          schema:
            $ref: "#/components/schemas/ExecutingWsMessage"
        - type: executed
          schema:
            $ref: "#/components/schemas/ExecutedWsMessage"
        - type: execution_start
          schema:
            $ref: "#/components/schemas/ExecutionStartWsMessage"
        - type: execution_success
          schema:
            $ref: "#/components/schemas/ExecutionSuccessWsMessage"
        - type: execution_cached
          schema:
            $ref: "#/components/schemas/ExecutionCachedWsMessage"
        - type: execution_interrupted
          schema:
            $ref: "#/components/schemas/ExecutionInterruptedWsMessage"
        - type: execution_error
          schema:
            $ref: "#/components/schemas/ExecutionErrorWsMessage"
        - type: logs
          schema:
            $ref: "#/components/schemas/LogsWsMessage"
        - type: notification
          schema:
            $ref: "#/components/schemas/NotificationWsMessage"
        - type: feature_flags
          schema:
            $ref: "#/components/schemas/FeatureFlagsWsMessage"
        - type: asset_download
          schema:
            $ref: "#/components/schemas/AssetDownloadWsMessage"
        - type: asset_export
          schema:
            $ref: "#/components/schemas/AssetExportWsMessage"

  # ---------------------------------------------------------------------------
  # Prompt
  # ---------------------------------------------------------------------------
  /api/prompt:
    get:
      operationId: getPromptInfo
      tags: [prompt]
      summary: Get queue status
      description: Returns how many items remain in the execution queue.
      responses:
        "200":
          description: Queue info
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PromptInfo"
    post:
      operationId: executePrompt
      tags: [prompt]
      summary: Submit a workflow for execution
      description: Submits a workflow for execution. The server validates the graph, assigns a `prompt_id`, and enqueues it. Clients listen on `/ws` for execution progress and output messages.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/PromptRequest"
      responses:
        "200":
          description: Prompt accepted
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PromptResponse"
        "400":
          description: Validation or node errors
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/PromptErrorResponse"

  # ---------------------------------------------------------------------------
  # Queue
  # ---------------------------------------------------------------------------
  /api/queue:
    get:
      operationId: getQueue
      tags: [queue]
      summary: Get running and pending queue items
      description: Returns the server's current execution queue, split into the currently-running prompt and the list of pending prompts.
      responses:
        "200":
          description: Queue contents
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/QueueInfo"
    post:
      operationId: manageQueue
      tags: [queue]
      summary: Clear or delete items from the queue
      description: Mutates the execution queue. Supports clearing all queued prompts or deleting individual prompts by ID.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/QueueManageRequest"
      responses:
        "200":
          description: Queue updated

  /api/interrupt:
    post:
      operationId: interruptExecution
      tags: [queue]
      summary: Interrupt current execution
      description: Interrupts the prompt that is currently executing. The next queued prompt (if any) will start immediately after.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                prompt_id:
                  type: string
                  format: uuid
                  description: "If provided, only interrupts this specific running prompt. Otherwise interrupts all."
      responses:
        "200":
          description: Interrupt signal sent

  /api/free:
    post:
      operationId: freeMemory
      tags: [queue]
      summary: Free GPU memory and/or unload models
      description: Frees GPU memory by unloading models and/or freeing the resident model cache, controlled by the request flags.
      requestBody:
        required: false
        content:
          application/json:
            schema:
              type: object
              properties:
                unload_models:
                  type: boolean
                  description: Unload all models from VRAM/RAM
                free_memory:
                  type: boolean
                  description: Run garbage collection and free cached memory
      responses:
        "200":
          description: Memory freed

  # ---------------------------------------------------------------------------
  # Jobs
  # ---------------------------------------------------------------------------
  /api/jobs:
    get:
      operationId: listJobs
      tags: [queue]
      summary: List jobs with filtering and pagination
      description: Returns a paginated list of completed prompt executions, newest first.
      parameters:
        - name: status
          in: query
          schema:
            type: string
          description: Filter by job status
        - name: workflow_id
          in: query
          schema:
            type: string
          description: Filter by workflow ID
        - name: sort_by
          in: query
          schema:
            type: string
          description: Field to sort by
        - name: sort_order
          in: query
          schema:
            type: string
            enum: [asc, desc]
          description: Sort direction
        - name: limit
          in: query
          schema:
            type: integer
          description: Maximum number of results (default is unlimited/None)
        - name: offset
          in: query
          schema:
            type: integer
            default: 0
          description: Pagination offset
      responses:
        "200":
          description: Jobs list
          content:
            application/json:
              schema:
                type: object
                properties:
                  jobs:
                    type: array
                    items:
                      $ref: "#/components/schemas/JobEntry"
                  pagination:
                    $ref: "#/components/schemas/PaginationInfo"

  /api/jobs/{job_id}:
    get:
      operationId: getJob
      tags: [queue]
      summary: Get a single job by ID
      description: Returns the full record for a single completed prompt execution, including its outputs, status, and metadata.
      parameters:
        - name: job_id
          in: path
          description: The job (prompt) ID to fetch.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Job detail
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/JobDetailResponse"
        "404":
          description: Job not found

  # ---------------------------------------------------------------------------
  # History
  # ---------------------------------------------------------------------------
  /api/history:
    get:
      operationId: getHistory
      tags: [history]
      summary: Get execution history
      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.

        Returns a dictionary keyed by prompt_id. Each value is a HistoryEntry
        containing prompt metadata, outputs, status, and node meta.
      parameters:
        - $ref: "#/components/parameters/ComfyUserHeader"
        - name: max_items
          in: query
          schema:
            type: integer
          description: Maximum number of history entries to return
        - name: offset
          in: query
          schema:
            type: integer
          description: Pagination offset (number of entries to skip)
      responses:
        "200":
          description: History dictionary keyed by prompt_id
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/HistoryEntry"
    post:
      operationId: manageHistory
      tags: [history]
      summary: Clear or delete history entries
      deprecated: true
      description: |
        **Deprecated.** Superseded by the forthcoming job-management endpoints
        under `/api/jobs`. Planned for removal no earlier than a future major
        release; sunset timeline TBD.
      parameters:
        - $ref: "#/components/parameters/ComfyUserHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: "#/components/schemas/HistoryManageRequest"
      responses:
        "200":
          description: History updated

  /api/history/{prompt_id}:
    get:
      operationId: getHistoryByPromptId
      tags: [history]
      summary: Get history for a specific prompt
      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.
      parameters:
        - $ref: "#/components/parameters/ComfyUserHeader"
        - name: prompt_id
          in: path
          description: The prompt ID to fetch history for.
          required: true
          schema:
            type: string
            format: uuid
      responses:
        "200":
          description: Single-entry history dictionary. Returns an empty object `{}` if the prompt_id is not found.
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/HistoryEntry"

  # ---------------------------------------------------------------------------
  # Upload
  # ---------------------------------------------------------------------------
  /api/upload/image:
    post:
      operationId: uploadImage
      tags: [upload]
      summary: Upload an image file
      description: Uploads an image file into one of the input/output/temp directories so it can be referenced by workflow nodes.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - image
              properties:
                image:
                  type: string
                  format: binary
                  description: Image file to upload
                type:
                  type: string
                  enum: [input, temp, output]
                  default: input
                  description: Target directory type
                overwrite:
                  type: string
                  description: 'Set to "true" to overwrite existing files'
                subfolder:
                  type: string
                  description: Subfolder within the target directory
      responses:
        "200":
          description: Upload result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResult"
        "400":
          description: No file provided or invalid request

  /api/upload/mask:
    post:
      operationId: uploadMask
      tags: [upload]
      deprecated: true
      summary: Upload a mask image (deprecated)
      description: |
        Deprecated. Clients should composite the mask onto the source image
        client-side and upload the resulting image via POST /api/upload/image
        instead. This endpoint will continue to function for older clients,
        but will not receive new features.

        Uploads a mask image associated with a previously-uploaded reference image.
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              required:
                - image
                - original_ref
              properties:
                image:
                  type: string
                  format: binary
                  description: Mask image (alpha channel is used)
                original_ref:
                  type: object
                  description: Reference to the original image file
                  required:
                    - filename
                  properties:
                    filename:
                      type: string
                      description: Filename of the original image
                  additionalProperties: true
                type:
                  type: string
                  enum: [input, temp, output]
                  default: input
                  description: Target directory type
                overwrite:
                  type: string
                  description: 'Set to "true" to overwrite existing files'
                subfolder:
                  type: string
                  description: Subfolder within the target directory
      responses:
        "200":
          description: Upload result
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/UploadResult"
        "400":
          description: No file provided or invalid request

  # ---------------------------------------------------------------------------
  # View
  # ---------------------------------------------------------------------------
  /api/view:
    get:
      operationId: viewFile
      tags: [view]
      summary: View or download a file
      description: Serves a file (image, audio, or video) from the input/output/temp directory identified by the query parameters.
      parameters:
        - name: filename
          in: query
          required: true
          schema:
            type: string
          description: Name of the file to view
        - name: type
          in: query
          schema:
            type: string
            enum: [input, output, temp]
            default: output
          description: Directory type
        - name: subfolder
          in: query
          schema:
            type: string
          description: Subfolder within the directory
        - name: preview
          in: query
          schema:
            type: string
          description: Preview format hint (e.g. "webp;90")
        - name: channel
          in: query
          schema:
            type: string
            enum: [rgba, rgb, a]
          description: Channel extraction mode
      responses:
        "200":
          description: File content
          content:
            image/*:
              schema:
                type: string
                format: binary
            video/*:
              schema:
                type: string
                format: binary
            audio/*:
              schema:
                type: string
                format: binary
            application/octet-stream:
              schema:
                type: string
                format: binary
        "404":
          description: File not found

  /api/view_metadata/{folder_name}:
    get:
      operationId: viewMetadata
      tags: [view]
      summary: Get metadata for a file (e.g. safetensors header)
      description: Returns embedded metadata parsed from a file in the given folder — for example, the header of a safetensors model.
      parameters:
        - name: folder_name
          in: path
          required: true
          schema:
            type: string
          description: Folder type (output, input, temp, etc.)
        - name: filename
          in: query
          required: true
          schema:
            type: string
          description: Filename to read metadata from
      responses:
        "200":
          description: File metadata
          content:
            application/json:
              schema:
                type: object
                additionalProperties: true
        "404":
          description: File or metadata not found

  # ---------------------------------------------------------------------------
  # System
  # ---------------------------------------------------------------------------
  /api/system_stats:
    get:
      operationId: getSystemStats
      tags: [system]
      summary: Get system statistics
      description: Returns hardware, Python, VRAM, and runtime statistics for the running ComfyUI process.
      responses:
        "200":
          description: System stats
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/SystemStatsResponse"

  /api/features:
    get:
      operationId: getFeatures
      tags: [system]
      summary: Get enabled feature flags
      description: Returns a dictionary of feature flag names to their enabled state. Cloud deployments may include additional typed fields alongside the boolean flags.
      responses:
        "200":
          description: Feature flags
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: boolean
                properties:
                  max_upload_size:
                    type: integer
                    format: int64
                    minimum: 0
                    description: "Maximum file upload size in bytes."
                  free_tier_credits:
                    type: integer
                    format: int32
                    minimum: 0
                    nullable: true
                    x-runtime: [cloud]
                    description: "[cloud-only] Credits available to free-tier users. Local ComfyUI returns null."
                  posthog_api_host:
                    type: string
                    format: uri
                    nullable: true
                    x-runtime: [cloud]
                    description: "[cloud-only] PostHog analytics proxy URL for frontend telemetry. Local ComfyUI returns null."
                  max_concurrent_jobs:
                    type: integer
                    format: int32
                    minimum: 0
                    nullable: true
                    x-runtime: [cloud]
                    description: "[cloud-only] Maximum concurrent jobs the authenticated user can run. Local ComfyUI returns null."
                  workflow_templates_version:
                    type: string
                    nullable: true
                    x-runtime: [cloud]
                    description: "[cloud-only] Version identifier for the workflow templates bundle. Local ComfyUI returns null."
                  workflow_templates_source:
                    type: string
                    nullable: true
                    enum: [dynamic_config_override, workflow_templates_version_json]
                    x-runtime: [cloud]
                    description: "[cloud-only] How the templates version was resolved. Local ComfyUI returns null."

  # ---------------------------------------------------------------------------
  # Node / Object Info
  # ---------------------------------------------------------------------------
  /api/object_info:
    get:
      operationId: getObjectInfo
      tags: [node]
      summary: Get all node definitions
      description: |
        Returns a dictionary of every registered node class, keyed by class name.
        Each value is a NodeInfo object describing inputs, outputs, category, etc.
      responses:
        "200":
          description: All node definitions
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/NodeInfo"

  /api/object_info/{node_class}:
    get:
      operationId: getObjectInfoByClass
      tags: [node]
      summary: Get a single node definition
      description: Returns the `NodeInfo` definition for a single registered node class.
      parameters:
        - name: node_class
          in: path
          required: true
          schema:
            type: string
          description: Node class name (e.g. "KSampler")
      responses:
        "200":
          description: Single node definition
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: "#/components/schemas/NodeInfo"
        "404":
          description: Node class not found

  /api/embeddings:
    get:
      operationId: getEmbeddings
      tags: [node]
      summary: List available embedding names
      description: Returns the list of text-encoder embeddings available on disk.
      responses:
        "200":
          description: Embedding names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  # ---------------------------------------------------------------------------
  # Models
  # ---------------------------------------------------------------------------
  /api/models:
    get:
      operationId: getModelTypes
      tags: [model]
      summary: List model folder type names
      description: Returns an array of model type names (e.g. checkpoints, loras, vae).
      responses:
        "200":
          description: Model type names
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string

  /api/models/{folder}:
    get:
      operationId: getModelsByFolder
      tags: [model]
      summary: List model filenames in a folder
      description: Returns the names of model files in the given folder. This endpoint predates `/api/experiment/models/{folder}` and returns names only — prefer the experiment endpoint for new integrations.
      parameters:
        - name: folder
          in: path
          required: true
          schema:
            type: string
          description: Model folder type name
      responses:
        "200":
          description: Model filenames
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        "404":
          description: Unknown folder type

  /api/experiment/models:
    get:
      operationId: getExperimentModels
      tags: [model]
      summary: List model folders with paths
      description: Returns an array of model folder objects with name and folder paths.
      responses:
        "200":
          description: Model folders
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ModelFolder"

  /api/experiment/models/{folder}:
    get:
      operationId: getExperimentModelsByFolder
      tags: [model]
      summary: List model files with metadata
      description: Returns the model files in the given folder with richer metadata (path index, mtime, size) than the legacy `/api/models/{folder}` endpoint.
      parameters:
        - name: folder
          in: path
          required: true
          schema:
            type: string
          description: Model folder type name
      responses:
        "200":
          description: Model files with metadata
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: "#/components/schemas/ModelFile"
        "404":
          description: Unknown folder type

  /api/experiment/models/preview/{folder}/{path_index}/{filename}:
    get:
      operationId: getModelPreview
      tags: [model]
      summary: Get model preview image
      description: Returns the preview image associated with a model file, if one exists alongside the model on disk.
      parameters:
        - name: folder
          in: path
          required: true
          schema:
            type: string
          description: Model folder type name
        - name: path_index
          in: path
          required: true
          schema:
            type: integer
          description: Path index within the folder
        - name: filename
          in: path
          required: true
          schema:
            type: string
          description: Model filename
      responses:
        "200":
          description: Preview image (WebP)
          content:
            image/webp:
              schema:
                type: string
                format: binary
        "404":
          description: Preview not found

  # ---------------------------------------------------------------------------
  # Users
  # ---------------------------------------------------------------------------
  /api/users:
    get:
      operationId: getUsers
      tags: [user]
      summary: Get user storage info
      description: |
        Returns user storage configuration. In single-user mode returns
        `{"storage": "server", "migrated": true/false}`. In multi-user mode
        returns `{"storage": "server", "users": {"user_id": "user_dir", ...}}`.
      parameters:
        - $ref: "#/components/parameters/ComfyUserHeader"
      responses:
        "200":
          description: User info
          content:
            application/json:
              schema:
                type: object
                properties:
                  storage:
                    type: string
                    description: Storage backend type (always "server")
                  migrated:
                    type: boolean
                    description: Whether migration from browser storage is complete (single-user)
                  users:
                    type: object
                    additionalProperties:
                      type: string
                    description: Map of user_id to directory name (multi-user)
    post:
      operationId: createUser
      tags: [user]
      summary: Create a new user (multi-user mode)
      description: Creates a new user entry. Only meaningful when ComfyUI is running in multi-user mode.
      parameters:
        - $ref: "#/components/parameters/ComfyUserHeader"
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - username
              properties:
                username:
                  type: string
                  description: Username for the new user
      responses:
        "200":
          description: Created user ID
          content:
            application/json:
              schema:
                type: string
                description: The generated user_id
        "400":
          description: Username already exists or invalid

  # ---------------------------------------------------------------------------
  # Userdata
  # ---------------------------------------------------------------------------
  /api/userdata:
    get:
      operationId: listUserdata
      tags: [userdata]
      summary: List files in a userdata directory
      description: Lists files in the authenticated user's data directory. Returns either filename strings or full objects depending on the `full_info` query parameter.
      parameters:
        - $ref: "#/components/parameters/ComfyUserHeader"
        - name: dir
          in: query
          required: true
          schema:
            type: string
          description: Directory path relative to the user's data folder
        - name: recurse
          in: query
          schema:
            type: boolean
          description: Recurse into subdirectories
        - name: full_info
          in: query
          schema:
            type: boolean
          description: Return full file info objects instead of just names
        - name: split
          in: query
          schema:
            type: boolean
          description: Split paths into directory components
      responses:
        "200":
          description: File listing
          content:
            application/json:
              schema:
                $ref: "#/components/schemas/ListUserdataResponse"
        "404":
          description: Directory not found

  /api/v2/userdata:
    get:
      operationId: listUserdataV2
      tags: [userdata]
      summary: List files in userdata (v2 format)
      description: Lists files in the authenticated user's data directory using the v2 response shape, which always returns full objects.
      parameters:
        - $ref: "#/components/parameters/ComfyUserHeader"
        - name: path