ComfyUI-Manager/openapi.yaml
bymyself 49549ddcb8 [feat] Implement comprehensive batch tracking and OpenAPI-driven data models
Enhances ComfyUI Manager with robust batch execution tracking and unified data model architecture:

- Implemented automatic batch history serialization with before/after system state snapshots
- Added comprehensive state management capturing installed nodes, models, and ComfyUI version info
- Enhanced task queue with proper client ID handling and WebSocket notifications
- Migrated all data models to OpenAPI-generated Pydantic models for consistency
- Added documentation for new TaskQueue methods (done_count, total_count, finalize)
- Fixed 64 linting errors with proper imports and code cleanup

Technical improvements:
- All models now auto-generated from openapi.yaml ensuring API/implementation consistency
- Batch tracking captures complete system state at operation start and completion
- Enhanced REST endpoints with comprehensive documentation
- Removed manual model files in favor of single source of truth
- Added helper methods for system state capture and batch lifecycle management
2025-06-08 01:18:14 -07:00

1225 lines
35 KiB
YAML

openapi: 3.1.0
info:
title: ComfyUI-Manager API
description: |
API for ComfyUI-Manager, a comprehensive management tool for ComfyUI custom nodes, models, and components.
This API enables programmatic access to node management, model downloading, snapshot operations,
and overall system configuration.
version: "3.32.3"
contact:
name: ComfyUI-Manager Maintainers
servers:
- url: '/'
description: Default ComfyUI server
# Common API components
components:
schemas:
# Core Task Queue Models
QueueTaskItem:
type: object
properties:
ui_id:
type: string
description: Unique identifier for the task
client_id:
type: string
description: Client identifier that initiated the task
kind:
type: string
description: Type of task being performed
enum: [install, uninstall, update, update-all, update-comfyui, fix, disable, enable, install-model]
required: [ui_id, client_id, kind]
TaskHistoryItem:
type: object
properties:
ui_id:
type: string
description: Unique identifier for the task
client_id:
type: string
description: Client identifier that initiated the task
kind:
type: string
description: Type of task that was performed
timestamp:
type: string
format: date-time
description: ISO timestamp when task completed
result:
type: string
description: Task result message or details
status:
$ref: '#/components/schemas/TaskExecutionStatus'
required: [ui_id, client_id, kind, timestamp, result]
TaskExecutionStatus:
type: object
properties:
status_str:
type: string
enum: [success, error, skip]
description: Overall task execution status
completed:
type: boolean
description: Whether the task completed
messages:
type: array
items:
type: string
description: Additional status messages
required: [status_str, completed, messages]
TaskStateMessage:
type: object
properties:
history:
type: object
additionalProperties:
$ref: '#/components/schemas/TaskHistoryItem'
description: Map of task IDs to their history items
running_queue:
type: array
items:
$ref: '#/components/schemas/QueueTaskItem'
description: Currently executing tasks
pending_queue:
type: array
items:
$ref: '#/components/schemas/QueueTaskItem'
description: Tasks waiting to be executed
required: [history, running_queue, pending_queue]
# WebSocket Message Models
ManagerMessageName:
type: string
enum: [cm-task-completed, cm-task-started, cm-queue-status]
description: WebSocket message type constants for manager events
MessageTaskDone:
type: object
properties:
ui_id:
type: string
description: Task identifier
result:
type: string
description: Task result message
kind:
type: string
description: Type of task
status:
$ref: '#/components/schemas/TaskExecutionStatus'
timestamp:
type: string
format: date-time
description: ISO timestamp when task completed
state:
$ref: '#/components/schemas/TaskStateMessage'
required: [ui_id, result, kind, timestamp, state]
MessageTaskStarted:
type: object
properties:
ui_id:
type: string
description: Task identifier
kind:
type: string
description: Type of task
timestamp:
type: string
format: date-time
description: ISO timestamp when task started
state:
$ref: '#/components/schemas/TaskStateMessage'
required: [ui_id, kind, timestamp, state]
MessageTaskFailed:
type: object
properties:
ui_id:
type: string
description: Task identifier
error:
type: string
description: Error message
kind:
type: string
description: Type of task
timestamp:
type: string
format: date-time
description: ISO timestamp when task failed
state:
$ref: '#/components/schemas/TaskStateMessage'
required: [ui_id, error, kind, timestamp, state]
MessageUpdate:
oneOf:
- $ref: '#/components/schemas/MessageTaskDone'
- $ref: '#/components/schemas/MessageTaskStarted'
- $ref: '#/components/schemas/MessageTaskFailed'
description: Union type for all possible WebSocket message updates
# Manager Package Models
ManagerPackInfo:
type: object
properties:
id:
type: string
description: Either github-author/github-repo or name of pack from the registry
version:
type: string
description: Semantic version or Git commit hash
ui_id:
type: string
description: Task ID - generated internally
required: [id, version]
ManagerPackInstalled:
type: object
properties:
ver:
type: string
description: The version of the pack that is installed (Git commit hash or semantic version)
cnr_id:
type: string
nullable: true
description: The name of the pack if installed from the registry
aux_id:
type: string
nullable: true
description: The name of the pack if installed from github (author/repo-name format)
enabled:
type: boolean
description: Whether the pack is enabled
required: [ver, enabled]
SelectedVersion:
type: string
enum: [latest, nightly]
description: Version selection for pack installation
ManagerChannel:
type: string
enum: [default, recent, legacy, forked, dev, tutorial]
description: Channel for pack sources
ManagerDatabaseSource:
type: string
enum: [remote, local, cache]
description: Source for pack information
ManagerPackState:
type: string
enum: [installed, disabled, not_installed, import_failed, needs_update]
description: Current state of a pack
ManagerPackInstallType:
type: string
enum: [git-clone, copy, cnr]
description: Type of installation used for the pack
ManagerPack:
allOf:
- $ref: '#/components/schemas/ManagerPackInfo'
- type: object
properties:
author:
type: string
description: Pack author name or 'Unclaimed' if added via GitHub crawl
files:
type: array
items:
type: string
description: Files included in the pack
reference:
type: string
description: The type of installation reference
title:
type: string
description: The display name of the pack
cnr_latest:
$ref: '#/components/schemas/SelectedVersion'
repository:
type: string
description: GitHub repository URL
state:
$ref: '#/components/schemas/ManagerPackState'
update-state:
type: string
enum: ['false', 'true']
nullable: true
description: Update availability status
stars:
type: integer
description: GitHub stars count
last_update:
type: string
format: date-time
description: Last update timestamp
health:
type: string
description: Health status of the pack
description:
type: string
description: Pack description
trust:
type: boolean
description: Whether the pack is trusted
install_type:
$ref: '#/components/schemas/ManagerPackInstallType'
# Installation Parameters
InstallPackParams:
allOf:
- $ref: '#/components/schemas/ManagerPackInfo'
- type: object
properties:
selected_version:
oneOf:
- type: string
- $ref: '#/components/schemas/SelectedVersion'
description: Semantic version, Git commit hash, latest, or nightly
repository:
type: string
description: GitHub repository URL (required if selected_version is nightly)
pip:
type: array
items:
type: string
description: PyPi dependency names
mode:
$ref: '#/components/schemas/ManagerDatabaseSource'
channel:
$ref: '#/components/schemas/ManagerChannel'
skip_post_install:
type: boolean
description: Whether to skip post-installation steps
required: [selected_version, mode, channel]
UpdateAllPacksParams:
type: object
properties:
mode:
$ref: '#/components/schemas/ManagerDatabaseSource'
ui_id:
type: string
description: Task ID - generated internally
# Queue Status Models
QueueStatus:
type: object
properties:
total_count:
type: integer
description: Total number of tasks (pending + running)
done_count:
type: integer
description: Number of completed tasks
in_progress_count:
type: integer
description: Number of tasks currently running
pending_count:
type: integer
description: Number of tasks waiting to be executed
is_processing:
type: boolean
description: Whether the task worker is active
client_id:
type: string
description: Client ID (when filtered by client)
required: [total_count, done_count, in_progress_count, is_processing]
# Mappings Model
ManagerMappings:
type: object
additionalProperties:
type: array
items:
- type: array
items:
type: string
description: List of ComfyNode names included in the pack
- type: object
properties:
title_aux:
type: string
description: The display name of the pack
# Model Management
ModelMetadata:
type: object
properties:
name:
type: string
description: Name of the model
type:
type: string
description: Type of model
base:
type: string
description: Base model type
save_path:
type: string
description: Path for saving the model
url:
type: string
description: Download URL
filename:
type: string
description: Target filename
ui_id:
type: string
description: ID for UI reference
required: [name, type, url, filename]
# Legacy Node Package Model (for backward compatibility)
NodePackageMetadata:
type: object
properties:
title:
type: string
description: Display name of the node package
name:
type: string
description: Repository/package name
files:
type: array
items:
type: string
description: Source URLs for the package
description:
type: string
description: Description of the node package functionality
install_type:
type: string
enum: [git, copy, pip]
description: Installation method
version:
type: string
description: Version identifier
id:
type: string
description: Unique identifier for the node package
ui_id:
type: string
description: ID for UI reference
channel:
type: string
description: Source channel
mode:
type: string
description: Source mode
# Snapshot Models
SnapshotItem:
type: string
description: Name of the snapshot
# Error Models
Error:
type: object
properties:
error:
type: string
description: Error message
required: [error]
# Response Models
InstalledPacksResponse:
type: object
additionalProperties:
$ref: '#/components/schemas/ManagerPackInstalled'
description: Map of pack names to their installation info
HistoryResponse:
type: object
properties:
history:
type: object
additionalProperties:
$ref: '#/components/schemas/TaskHistoryItem'
description: Map of task IDs to their history items
HistoryListResponse:
type: object
properties:
ids:
type: array
items:
type: string
description: List of available batch history IDs
# State Management Models
InstalledNodeInfo:
type: object
properties:
name:
type: string
description: Node package name
version:
type: string
description: Installed version
repository_url:
type: string
nullable: true
description: Git repository URL
install_method:
type: string
description: Installation method (cnr, git, pip, etc.)
enabled:
type: boolean
description: Whether the node is currently enabled
default: true
install_date:
type: string
format: date-time
nullable: true
description: ISO timestamp of installation
required: [name, version, install_method]
InstalledModelInfo:
type: object
properties:
name:
type: string
description: Model filename
path:
type: string
description: Full path to model file
type:
type: string
description: Model type (checkpoint, lora, vae, etc.)
size_bytes:
type: integer
nullable: true
description: File size in bytes
minimum: 0
hash:
type: string
nullable: true
description: Model file hash for verification
install_date:
type: string
format: date-time
nullable: true
description: ISO timestamp when added
required: [name, path, type]
ComfyUIVersionInfo:
type: object
properties:
version:
type: string
description: ComfyUI version string
commit_hash:
type: string
nullable: true
description: Git commit hash
branch:
type: string
nullable: true
description: Git branch name
is_stable:
type: boolean
description: Whether this is a stable release
default: false
last_updated:
type: string
format: date-time
nullable: true
description: ISO timestamp of last update
required: [version]
BatchOperation:
type: object
properties:
operation_id:
type: string
description: Unique operation identifier
operation_type:
type: string
description: Type of operation
enum: [install, update, uninstall, fix, disable, enable, install-model]
target:
type: string
description: Target of the operation (node name, model name, etc.)
target_version:
type: string
nullable: true
description: Target version for the operation
result:
type: string
description: Operation result
enum: [success, failed, skipped]
error_message:
type: string
nullable: true
description: Error message if operation failed
start_time:
type: string
format: date-time
description: ISO timestamp when operation started
end_time:
type: string
format: date-time
nullable: true
description: ISO timestamp when operation completed
client_id:
type: string
nullable: true
description: Client that initiated the operation
required: [operation_id, operation_type, target, result, start_time]
ComfyUISystemState:
type: object
properties:
snapshot_time:
type: string
format: date-time
description: ISO timestamp when snapshot was taken
comfyui_version:
$ref: '#/components/schemas/ComfyUIVersionInfo'
frontend_version:
type: string
nullable: true
description: ComfyUI frontend version if available
python_version:
type: string
description: Python interpreter version
platform_info:
type: string
description: Operating system and platform information
installed_nodes:
type: object
additionalProperties:
$ref: '#/components/schemas/InstalledNodeInfo'
description: Map of installed node packages by name
installed_models:
type: object
additionalProperties:
$ref: '#/components/schemas/InstalledModelInfo'
description: Map of installed models by name
manager_config:
type: object
additionalProperties: true
description: ComfyUI Manager configuration settings
required: [snapshot_time, comfyui_version, python_version, platform_info]
BatchExecutionRecord:
type: object
properties:
batch_id:
type: string
description: Unique batch identifier
start_time:
type: string
format: date-time
description: ISO timestamp when batch started
end_time:
type: string
format: date-time
nullable: true
description: ISO timestamp when batch completed
state_before:
$ref: '#/components/schemas/ComfyUISystemState'
state_after:
$ref: '#/components/schemas/ComfyUISystemState'
nullable: true
description: System state after batch execution
operations:
type: array
items:
$ref: '#/components/schemas/BatchOperation'
description: List of operations performed in this batch
total_operations:
type: integer
description: Total number of operations in batch
minimum: 0
default: 0
successful_operations:
type: integer
description: Number of successful operations
minimum: 0
default: 0
failed_operations:
type: integer
description: Number of failed operations
minimum: 0
default: 0
skipped_operations:
type: integer
description: Number of skipped operations
minimum: 0
default: 0
required: [batch_id, start_time, state_before]
securitySchemes:
securityLevel:
type: apiKey
in: header
name: Security-Level
description: Security level for sensitive operations
parameters:
modeParam:
name: mode
in: query
description: Source mode (e.g., "local", "remote")
schema:
$ref: '#/components/schemas/ManagerDatabaseSource'
targetParam:
name: target
in: query
description: Target identifier
required: true
schema:
type: string
valueParam:
name: value
in: query
description: New value to set
required: true
schema:
type: string
clientIdParam:
name: client_id
in: query
description: Client ID for filtering tasks
schema:
type: string
uiIdParam:
name: ui_id
in: query
description: Specific task ID to retrieve
schema:
type: string
maxItemsParam:
name: max_items
in: query
description: Maximum number of items to return
schema:
type: integer
minimum: 1
offsetParam:
name: offset
in: query
description: Offset for pagination
schema:
type: integer
minimum: 0
# API Paths
paths:
# Task Queue Management (v2 endpoints)
/v2/manager/queue/task:
post:
summary: Add task to queue
description: Adds a new task to the processing queue
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/QueueTaskItem'
responses:
'200':
description: Task queued successfully
/v2/manager/queue/status:
get:
summary: Get queue status
description: Returns the current status of the operation queue with optional client filtering
parameters:
- $ref: '#/components/parameters/clientIdParam'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/QueueStatus'
/v2/manager/queue/history:
get:
summary: Get task history
description: Get task history with optional filtering
parameters:
- name: id
in: query
description: Batch history ID (for file-based history)
schema:
type: string
- $ref: '#/components/parameters/clientIdParam'
- $ref: '#/components/parameters/uiIdParam'
- $ref: '#/components/parameters/maxItemsParam'
- $ref: '#/components/parameters/offsetParam'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
oneOf:
- $ref: '#/components/schemas/HistoryResponse'
- type: object # File-based batch history
'400':
description: Error retrieving history
/v2/manager/queue/history_list:
get:
summary: Get available batch history files
description: Returns a list of batch history IDs sorted by modification time
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/HistoryListResponse'
'400':
description: Error retrieving history list
/v2/manager/queue/batch/{batch_id}:
get:
summary: Get batch execution record
description: Returns detailed execution record for a specific batch including before/after state snapshots and all operations performed
parameters:
- name: batch_id
in: path
required: true
description: Unique batch identifier
schema:
type: string
responses:
'200':
description: Batch record retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/BatchExecutionRecord'
'404':
description: Batch not found
'400':
description: Error retrieving batch record
/v2/manager/queue/start:
get:
summary: Start queue processing
description: Starts processing the operation queue
responses:
'200':
description: Processing started
'201':
description: Processing already in progress
/v2/manager/queue/reset:
get:
summary: Reset queue
description: Resets the operation queue
responses:
'200':
description: Queue reset successfully
/v2/manager/queue/update_all:
get:
summary: Update all custom nodes
description: Queues update operations for all installed custom nodes
security:
- securityLevel: []
parameters:
- $ref: '#/components/parameters/modeParam'
responses:
'200':
description: Update queued successfully
'401':
description: Processing already in progress
'403':
description: Security policy violation
/v2/manager/queue/update_comfyui:
get:
summary: Update ComfyUI
description: Queues an update operation for ComfyUI itself
responses:
'200':
description: Update queued successfully
/v2/manager/queue/install_model:
post:
summary: Install model
description: Queues installation of a model
security:
- securityLevel: []
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ModelMetadata'
responses:
'200':
description: Installation queued successfully
'400':
description: Invalid model request
'403':
description: Security policy violation
# Custom Nodes Endpoints (v2)
/v2/customnode/getmappings:
get:
summary: Get node-to-package mappings
description: Provides unified mapping between nodes and node packages
parameters:
- $ref: '#/components/parameters/modeParam'
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/ManagerMappings'
/v2/customnode/fetch_updates:
get:
summary: Check for updates
description: Fetches updates for custom nodes
parameters:
- $ref: '#/components/parameters/modeParam'
responses:
'200':
description: No updates available
'201':
description: Updates found
'400':
description: Error occurred
/v2/customnode/installed:
get:
summary: Get installed custom nodes
description: Returns a list of installed node packages
parameters:
- name: mode
in: query
description: Lists mode, default or imported
schema:
type: string
enum: [default, imported]
responses:
'200':
description: Successful operation
content:
application/json:
schema:
$ref: '#/components/schemas/InstalledPacksResponse'
/v2/customnode/import_fail_info:
post:
summary: Get import failure information
description: Returns information about why a node failed to import
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
cnr_id:
type: string
url:
type: string
responses:
'200':
description: Successful operation
'400':
description: No information available
/v2/customnode/install/git_url:
post:
summary: Install custom node via Git URL
description: Installs a custom node from a Git repository URL
security:
- securityLevel: []
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Installation successful or already installed
'400':
description: Installation failed
'403':
description: Security policy violation
/v2/customnode/install/pip:
post:
summary: Install custom node dependencies via pip
description: Installs Python package dependencies for custom nodes
security:
- securityLevel: []
requestBody:
required: true
content:
text/plain:
schema:
type: string
responses:
'200':
description: Installation successful
'403':
description: Security policy violation
# Snapshot Management Endpoints (v2)
/v2/snapshot/getlist:
get:
summary: Get snapshot list
description: Returns a list of available snapshots
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
$ref: '#/components/schemas/SnapshotItem'
/v2/snapshot/remove:
get:
summary: Remove snapshot
description: Removes a specified snapshot
security:
- securityLevel: []
parameters:
- $ref: '#/components/parameters/targetParam'
responses:
'200':
description: Snapshot removed successfully
'400':
description: Error removing snapshot
'403':
description: Security policy violation
/v2/snapshot/restore:
get:
summary: Restore snapshot
description: Restores a specified snapshot
security:
- securityLevel: []
parameters:
- $ref: '#/components/parameters/targetParam'
responses:
'200':
description: Snapshot restoration scheduled
'400':
description: Error restoring snapshot
'403':
description: Security policy violation
/v2/snapshot/get_current:
get:
summary: Get current snapshot
description: Returns the current system state as a snapshot
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
'400':
description: Error creating snapshot
/v2/snapshot/save:
get:
summary: Save snapshot
description: Saves the current system state as a new snapshot
responses:
'200':
description: Snapshot saved successfully
'400':
description: Error saving snapshot
# ComfyUI Management Endpoints (v2)
/v2/comfyui_manager/comfyui_versions:
get:
summary: Get ComfyUI versions
description: Returns available and current ComfyUI versions
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
versions:
type: array
items:
type: string
current:
type: string
'400':
description: Error retrieving versions
/v2/comfyui_manager/comfyui_switch_version:
get:
summary: Switch ComfyUI version
description: Switches to a specified ComfyUI version
parameters:
- name: ver
in: query
description: Target version
schema:
type: string
responses:
'200':
description: Version switch successful
'400':
description: Error switching version
# Configuration Endpoints (v2)
/v2/manager/preview_method:
get:
summary: Get or set preview method
description: Gets or sets the latent preview method
parameters:
- name: value
in: query
required: false
description: New preview method
schema:
type: string
enum: [auto, latent2rgb, taesd, none]
responses:
'200':
description: Setting updated or current value returned
content:
text/plain:
schema:
type: string
/v2/manager/db_mode:
get:
summary: Get or set database mode
description: Gets or sets the database mode
parameters:
- name: value
in: query
required: false
description: New database mode
schema:
type: string
enum: [channel, local, remote]
responses:
'200':
description: Setting updated or current value returned
content:
text/plain:
schema:
type: string
/v2/manager/policy/update:
get:
summary: Get or set update policy
description: Gets or sets the update policy
parameters:
- name: value
in: query
required: false
description: New update policy
schema:
type: string
enum: [stable, nightly, nightly-comfyui]
responses:
'200':
description: Setting updated or current value returned
content:
text/plain:
schema:
type: string
/v2/manager/channel_url_list:
get:
summary: Get or set channel URL
description: Gets or sets the channel URL for custom node sources
parameters:
- name: value
in: query
required: false
description: New channel name
schema:
type: string
responses:
'200':
description: Setting updated or channel list returned
content:
application/json:
schema:
type: object
properties:
selected:
type: string
list:
type: array
items:
type: object
properties:
name:
type: string
url:
type: string
/v2/manager/reboot:
get:
summary: Reboot ComfyUI
description: Restarts the ComfyUI server
security:
- securityLevel: []
responses:
'200':
description: Reboot initiated
'403':
description: Security policy violation
/v2/manager/version:
get:
summary: Get manager version
description: Returns the current version of ComfyUI-Manager
responses:
'200':
description: Successful operation
content:
text/plain:
schema:
type: string
/v2/manager/is_legacy_manager_ui:
get:
summary: Check if legacy manager UI is enabled
description: Returns whether the legacy manager UI is enabled
responses:
'200':
description: Successful operation
content:
application/json:
schema:
type: object
properties:
is_legacy_manager_ui:
type: boolean