openapi: 3.0.3
info:
  title: ComfyUI API
  description: |
    API for ComfyUI - A powerful and modular UI for Stable Diffusion.
    
    This API allows you to interact with ComfyUI programmatically, including:
    - Submitting workflows for execution
    - Managing the execution queue
    - Retrieving generated images
    - Managing models
    - Retrieving node information
  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

tags:
  - name: workflow
    description: Workflow execution and management
  - name: queue
    description: Queue management
  - name: image
    description: Image handling
  - name: node
    description: Node information
  - name: model
    description: Model management
  - name: system
    description: System information
  - name: internal
    description: Internal API routes

paths:
  /prompt:
    get:
      tags:
        - workflow
      summary: Get information about current prompt execution
      description: Returns information about the current prompt in the execution queue
      operationId: getPromptInfo
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptInfo'
    post:
      tags:
        - workflow
      summary: Submit a workflow for execution
      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:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PromptRequest'
      responses:
        '200':
          description: Success - Prompt accepted
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PromptResponse'
        '400':
          description: Invalid prompt
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ErrorResponse'

  /queue:
    get:
      tags:
        - queue
      summary: Get queue information
      description: Returns information about running and pending items in the queue
      operationId: getQueueInfo
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/QueueInfo'
    post:
      tags:
        - queue
      summary: Manage queue
      description: Clear the queue or delete specific items
      operationId: manageQueue
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                clear:
                  type: boolean
                  description: If true, clears the entire queue
                delete:
                  type: array
                  description: Array of prompt IDs to delete from the queue
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Success
          
  /interrupt:
    post:
      tags:
        - workflow
      summary: Interrupt the current execution
      description: Interrupts the currently running workflow execution
      operationId: interruptExecution
      responses:
        '200':
          description: Success
          
  /free:
    post:
      tags:
        - system
      summary: Free resources
      description: Unload models and/or free memory
      operationId: freeResources
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                unload_models:
                  type: boolean
                  description: If true, unloads models from memory
                free_memory:
                  type: boolean
                  description: If true, frees GPU memory
      responses:
        '200':
          description: Success
          
  /history:
    get:
      tags:
        - workflow
      summary: Get execution history
      description: Returns the history of executed workflows
      operationId: getHistory
      parameters:
        - name: max_items
          in: query
          description: Maximum number of history items to return
          required: false
          schema:
            type: integer
            format: int32
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/HistoryItem'
    post:
      tags:
        - workflow
      summary: Manage history
      description: Clear history or delete specific items
      operationId: manageHistory
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                clear:
                  type: boolean
                  description: If true, clears the entire history
                delete:
                  type: array
                  description: Array of prompt IDs to delete from history
                  items:
                    type: string
                    format: uuid
      responses:
        '200':
          description: Success
          
  /history/{prompt_id}:
    get:
      tags:
        - workflow
      summary: Get specific history item
      description: Returns a specific history item by ID
      operationId: getHistoryItem
      parameters:
        - name: prompt_id
          in: path
          description: ID of the prompt to retrieve
          required: true
          schema:
            type: string
            format: uuid
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/HistoryItem'
                
  /object_info:
    get:
      tags:
        - node
      summary: Get all node information
      description: Returns information about all available nodes
      operationId: getNodeInfo
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/NodeInfo'
                
  /object_info/{node_class}:
    get:
      tags:
        - node
      summary: Get specific node information
      description: Returns information about a specific node class
      operationId: getNodeClassInfo
      parameters:
        - name: node_class
          in: path
          description: Name of the node class
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  $ref: '#/components/schemas/NodeInfo'
                  
  /upload/image:
    post:
      tags:
        - image
      summary: Upload an image
      description: Uploads an image to the server
      operationId: uploadImage
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: The image file to upload
                overwrite:
                  type: string
                  description: Whether to overwrite if file exists (true/false)
                type:
                  type: string
                  enum: [input, temp, output]
                  description: Type of directory to store the image in
                subfolder:
                  type: string
                  description: Subfolder to store the image in
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: Filename of the uploaded image
                  subfolder:
                    type: string
                    description: Subfolder the image was stored in
                  type:
                    type: string
                    description: Type of directory the image was stored in
        '400':
          description: Bad request
          
  /upload/mask:
    post:
      tags:
        - image
      summary: Upload a mask for an image
      description: Uploads a mask image and applies it to a referenced original image
      operationId: uploadMask
      requestBody:
        required: true
        content:
          multipart/form-data:
            schema:
              type: object
              properties:
                image:
                  type: string
                  format: binary
                  description: The mask image file to upload
                original_ref:
                  type: string
                  description: JSON string containing reference to the original image
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  name:
                    type: string
                    description: Filename of the uploaded mask
                  subfolder:
                    type: string
                    description: Subfolder the mask was stored in
                  type:
                    type: string
                    description: Type of directory the mask was stored in
        '400':
          description: Bad request
          
  /view:
    get:
      tags:
        - image
      summary: View an image
      description: Retrieves an image from the server
      operationId: viewImage
      parameters:
        - name: filename
          in: query
          description: Name of the file to retrieve
          required: true
          schema:
            type: string
        - name: type
          in: query
          description: Type of directory to retrieve from
          required: false
          schema:
            type: string
            enum: [input, temp, output]
            default: output
        - name: subfolder
          in: query
          description: Subfolder to retrieve from
          required: false
          schema:
            type: string
        - name: preview
          in: query
          description: Preview options (format;quality)
          required: false
          schema:
            type: string
        - name: channel
          in: query
          description: Channel to retrieve (rgb, a, rgba)
          required: false
          schema:
            type: string
            enum: [rgb, a, rgba]
            default: rgba
      responses:
        '200':
          description: Success
          content:
            image/*:
              schema:
                type: string
                format: binary
        '400':
          description: Bad request
        '404':
          description: File not found
          
  /view_metadata/{folder_name}:
    get:
      tags:
        - model
      summary: View model metadata
      description: Retrieves metadata from a safetensors file
      operationId: viewModelMetadata
      parameters:
        - name: folder_name
          in: path
          description: Name of the model folder
          required: true
          schema:
            type: string
        - name: filename
          in: query
          description: Name of the safetensors file
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
        '404':
          description: File not found
          
  /models:
    get:
      tags:
        - model
      summary: Get model types
      description: Returns a list of available model types
      operationId: getModelTypes
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  
  /models/{folder}:
    get:
      tags:
        - model
      summary: Get models of a specific type
      description: Returns a list of available models of a specific type
      operationId: getModels
      parameters:
        - name: folder
          in: path
          description: Model type folder
          required: true
          schema:
            type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '404':
          description: Folder not found
          
  /embeddings:
    get:
      tags:
        - model
      summary: Get embeddings
      description: Returns a list of available embeddings
      operationId: getEmbeddings
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  
  /extensions:
    get:
      tags:
        - system
      summary: Get extensions
      description: Returns a list of available extensions
      operationId: getExtensions
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
                  
  /system_stats:
    get:
      tags:
        - system
      summary: Get system statistics
      description: Returns system information including RAM, VRAM, and ComfyUI version
      operationId: getSystemStats
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/SystemStats'
                
  /ws:
    get:
      tags:
        - workflow
      summary: WebSocket connection
      description: |
        Establishes a WebSocket connection for real-time communication.
        This endpoint is used for receiving progress updates, status changes, and results from workflow executions.
      operationId: webSocketConnect
      parameters:
        - name: clientId
          in: query
          description: Optional client ID for reconnection
          required: false
          schema:
            type: string
      responses:
        '101':
          description: Switching Protocols to WebSocket
          
  /internal/logs:
    get:
      tags:
        - internal
      summary: Get logs
      description: Returns system logs as a single string
      operationId: getLogs
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: string
                
  /internal/logs/raw:
    get:
      tags:
        - internal
      summary: Get raw logs
      description: Returns raw system logs with terminal size information
      operationId: getRawLogs
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                properties:
                  entries:
                    type: array
                    items:
                      type: object
                      properties:
                        t:
                          type: string
                          description: Timestamp
                        m:
                          type: string
                          description: Message
                  size:
                    type: object
                    properties:
                      cols:
                        type: integer
                        description: Terminal columns
                      rows:
                        type: integer
                        description: Terminal rows
                        
  /internal/logs/subscribe:
    patch:
      tags:
        - internal
      summary: Subscribe to logs
      description: Subscribe or unsubscribe to log updates
      operationId: subscribeToLogs
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              properties:
                clientId:
                  type: string
                  description: Client ID
                enabled:
                  type: boolean
                  description: Whether to enable or disable subscription
      responses:
        '200':
          description: Success
          
  /internal/folder_paths:
    get:
      tags:
        - internal
      summary: Get folder paths
      description: Returns a map of folder names to their paths
      operationId: getFolderPaths
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: object
                additionalProperties:
                  type: string
                  
  /internal/files/{directory_type}:
    get:
      tags:
        - internal
      summary: Get files
      description: Returns a list of files in a specific directory type
      operationId: getFiles
      parameters:
        - name: directory_type
          in: path
          description: Type of directory (output, input, temp)
          required: true
          schema:
            type: string
            enum: [output, input, temp]
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                type: array
                items:
                  type: string
        '400':
          description: Invalid directory type

components:
  schemas:
    PromptRequest:
      type: object
      required:
        - prompt
      properties:
        prompt:
          type: object
          description: The workflow graph to execute
          additionalProperties: true
        number:
          type: number
          description: Priority number for the queue (lower numbers have higher priority)
        front:
          type: boolean
          description: If true, adds the prompt to the front of the queue
        extra_data:
          type: object
          description: Extra data to be associated with the prompt
          additionalProperties: true
        client_id:
          type: string
          description: Client ID for attribution of the prompt
          
    PromptResponse:
      type: object
      properties:
        prompt_id:
          type: string
          format: uuid
          description: Unique identifier for the prompt execution
        number:
          type: number
          description: Priority number in the queue
        node_errors:
          type: object
          description: Any errors in the nodes of the prompt
          additionalProperties: true
          
    ErrorResponse:
      type: object
      properties:
        error:
          type: object
          properties:
            type:
              type: string
              description: Error type
            message:
              type: string
              description: Error message
            details:
              type: string
              description: Detailed error information
            extra_info:
              type: object
              description: Additional error information
              additionalProperties: true
        node_errors:
          type: object
          description: Node-specific errors
          additionalProperties: true
          
    PromptInfo:
      type: object
      properties:
        exec_info:
          type: object
          properties:
            queue_remaining:
              type: integer
              description: Number of items remaining in the queue
              
    QueueInfo:
      type: object
      properties:
        queue_running:
          type: array
          items:
            type: object
            description: Currently running items
            additionalProperties: true
        queue_pending:
          type: array
          items:
            type: object
            description: Pending items in the queue
            additionalProperties: true
            
    HistoryItem:
      type: object
      properties:
        prompt_id:
          type: string
          format: uuid
          description: Unique identifier for the prompt
        prompt:
          type: object
          description: The workflow graph that was executed
          additionalProperties: true
        extra_data:
          type: object
          description: Additional data associated with the execution
          additionalProperties: true
        outputs:
          type: object
          description: Output data from the execution
          additionalProperties: true
        
    NodeInfo:
      type: object
      properties:
        input:
          type: object
          description: Input specifications for the node
          additionalProperties: true
        input_order:
          type: object
          description: Order of inputs for display
          additionalProperties:
            type: array
            items:
              type: string
        output:
          type: array
          items:
            type: string
          description: Output types of the node
        output_is_list:
          type: array
          items:
            type: boolean
          description: Whether each output is a list
        output_name:
          type: array
          items:
            type: string
          description: Names of the outputs
        name:
          type: string
          description: Internal name of the node
        display_name:
          type: string
          description: Display name of the node
        description:
          type: string
          description: Description of the node
        python_module:
          type: string
          description: Python module implementing the node
        category:
          type: string
          description: Category of the node
        output_node:
          type: boolean
          description: Whether this is an output node
        output_tooltips:
          type: array
          items:
            type: string
          description: Tooltips for outputs
        deprecated:
          type: boolean
          description: Whether the node is deprecated
        experimental:
          type: boolean
          description: Whether the node is experimental
        api_node:
          type: boolean
          description: Whether this is an API node
          
    SystemStats:
      type: object
      properties:
        system:
          type: object
          properties:
            os:
              type: string
              description: Operating system
            ram_total:
              type: number
              description: Total system RAM in bytes
            ram_free:
              type: number
              description: Free system RAM in bytes
            comfyui_version:
              type: string
              description: ComfyUI version
            python_version:
              type: string
              description: Python version
            pytorch_version:
              type: string
              description: PyTorch version
            embedded_python:
              type: boolean
              description: Whether using embedded Python
            argv:
              type: array
              items:
                type: string
              description: Command line arguments
        devices:
          type: array
          items:
            type: object
            properties:
              name:
                type: string
                description: Device name
              type:
                type: string
                description: Device type
              index:
                type: integer
                description: Device index
              vram_total:
                type: number
                description: Total VRAM in bytes
              vram_free:
                type: number
                description: Free VRAM in bytes
              torch_vram_total:
                type: number
                description: Total VRAM as reported by PyTorch
              torch_vram_free:
                type: number
                description: Free VRAM as reported by PyTorch