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