The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.
Add OpenAPI 3.1 specification for ComfyUI API (#13397)
Matt Miller443074eee92f
diff --git a/.gitignore b/.gitignoreindex 2700ad5c2..0ab4ba75e 100644--- a/.gitignore+++ b/.gitignore@@ -21,6 +21,5 @@ venv*/*.logweb_custom_versions/.DS_Store-openapi.yamlfiltered-openapi.yamluv.lockdiff --git a/openapi.yaml b/openapi.yamlnew file mode 100644index 000000000..77d0e2318--- /dev/null+++ b/openapi.yaml@@ -0,0 +1,3231 @@+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)++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]+ summary: Upload a mask image+ description: 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.+ responses:+ "200":+ description: Feature flags+ content:+ application/json:+ schema:+ type: object+ additionalProperties:+ type: boolean++ # ---------------------------------------------------------------------------+ # 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+ in: query+ schema:+ type: string+ description: Directory path relative to user data root+ responses:+ "200":+ description: File listing with metadata+ content:+ application/json:+ schema:+ type: array+ items:+ type: object+ properties:+ name:+ type: string+ path:+ type: string+ type:+ type: string+ enum: [file, directory]+ size:+ type: integer+ modified:+ type: number+ description: Unix timestamp++ /api/userdata/{file}:+ get:+ operationId: getUserdataFile+ tags: [userdata]+ summary: Read a userdata file+ description: Reads the contents of a file from the authenticated user's data directory.+ parameters:+ - $ref: "#/components/parameters/ComfyUserHeader"+ - name: file+ in: path+ required: true+ schema:+ type: string+ description: File path relative to user data directory+ responses:+ "200":+ description: File content+ content:+ application/octet-stream:+ schema:+ type: string+ format: binary+ "404":+ description: File not found+ post:+ operationId: writeUserdataFile+ tags: [userdata]+ summary: Write or create a userdata file+ description: Writes (creates or replaces) a file in the authenticated user's data directory.+ parameters:+ - $ref: "#/components/parameters/ComfyUserHeader"+ - name: file+ in: path+ required: true+ schema:+ type: string+ description: File path relative to user data directory+ - name: overwrite+ in: query+ schema:+ type: boolean+ description: Allow overwriting existing files+ - name: full_info+ in: query+ schema:+ type: boolean+ description: Return full file info in response+ requestBody:+ required: true+ content:+ application/octet-stream:+ schema:+ type: string+ format: binary+ application/json:+ schema: {}+ responses:+ "200":+ description: File written+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/UserDataResponse"+ "409":+ description: File exists and overwrite not set+ delete:+ operationId: deleteUserdataFile+ tags: [userdata]+ summary: Delete a userdata file+ description: Deletes a file from the authenticated user's data directory.+ parameters:+ - $ref: "#/components/parameters/ComfyUserHeader"+ - name: file+ in: path+ required: true+ schema:+ type: string+ description: File path relative to user data directory+ responses:+ "204":+ description: File deleted+ "404":+ description: File not found++ /api/userdata/{file}/move/{dest}:+ post:+ operationId: moveUserdataFile+ tags: [userdata]+ summary: Move or rename a userdata file+ description: Renames or moves a file within the authenticated user's data directory.+ parameters:+ - $ref: "#/components/parameters/ComfyUserHeader"+ - name: file+ in: path+ required: true+ schema:+ type: string+ description: Source file path+ - name: dest+ in: path+ required: true+ schema:+ type: string+ description: Destination file path+ - name: overwrite+ in: query+ schema:+ type: boolean+ description: Allow overwriting at destination+ - name: full_info+ in: query+ schema:+ type: boolean+ description: Return full file info in response+ responses:+ "200":+ description: File moved+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/UserDataResponse"+ "404":+ description: Source file not found+ "409":+ description: Destination exists and overwrite not set++ # ---------------------------------------------------------------------------+ # Settings+ # ---------------------------------------------------------------------------+ /api/settings:+ get:+ operationId: getSettings+ tags: [settings]+ summary: Get all user settings+ description: Returns all settings for the authenticated user.+ parameters:+ - $ref: "#/components/parameters/ComfyUserHeader"+ responses:+ "200":+ description: Settings object+ content:+ application/json:+ schema:+ type: object+ additionalProperties: true+ post:+ operationId: updateSettings+ tags: [settings]+ summary: Update user settings (partial merge)+ description: Replaces the authenticated user's settings with the provided object.+ parameters:+ - $ref: "#/components/parameters/ComfyUserHeader"+ requestBody:+ required: true+ content:+ application/json:+ schema:+ type: object+ additionalProperties: true+ description: Partial settings to merge+ responses:+ "200":+ description: Settings updated++ /api/settings/{id}:+ get:+ operationId: getSetting+ tags: [settings]+ summary: Get a single setting by key+ description: Returns the value of a single setting, identified by key.+ parameters:+ - $ref: "#/components/parameters/ComfyUserHeader"+ - name: id+ in: path+ required: true+ schema:+ type: string+ description: Setting key+ responses:+ "200":+ description: Setting value (null if the setting does not exist)+ content:+ application/json:+ schema:+ nullable: true+ description: The setting value (any JSON type), or null if not set+ post:+ operationId: updateSetting+ tags: [settings]+ summary: Set a single setting value+ description: Sets the value of a single setting, identified by key.+ parameters:+ - $ref: "#/components/parameters/ComfyUserHeader"+ - name: id+ in: path+ required: true+ schema:+ type: string+ description: Setting key+ requestBody:+ required: true+ content:+ application/json:+ schema:+ description: The setting value (any JSON type)+ responses:+ "200":+ description: Setting updated++ # ---------------------------------------------------------------------------+ # Extensions / Templates / i18n+ # ---------------------------------------------------------------------------+ /api/extensions:+ get:+ operationId: getExtensions+ tags: [extensions]+ summary: List frontend extension JS file paths+ description: Returns the list of frontend extension JS URLs registered by custom nodes, to be loaded by the frontend on startup.+ responses:+ "200":+ description: Array of JS file paths+ content:+ application/json:+ schema:+ type: array+ items:+ type: string+ description: Relative path to extension JS file++ /api/workflow_templates:+ get:+ operationId: getWorkflowTemplates+ tags: [extensions]+ summary: Get workflow template mappings+ description: Returns a map of custom node names to their provided workflow template names.+ responses:+ "200":+ description: Template mappings+ content:+ application/json:+ schema:+ type: object+ additionalProperties:+ type: array+ items:+ type: string+ description: Map of node pack name to array of template names++ /api/i18n:+ get:+ operationId: getI18n+ tags: [extensions]+ summary: Get internationalisation translation strings+ description: Returns the URLs of translation files contributed by custom nodes, keyed by locale.+ responses:+ "200":+ description: Translation map+ content:+ application/json:+ schema:+ type: object+ additionalProperties: true+ description: Nested map of locale to translation key-value pairs++ # ---------------------------------------------------------------------------+ # Subgraphs+ # ---------------------------------------------------------------------------+ /api/global_subgraphs:+ get:+ operationId: getGlobalSubgraphs+ tags: [subgraph]+ summary: List global subgraph blueprints+ description: Returns a dictionary of subgraph IDs to their metadata.+ responses:+ "200":+ description: Subgraph metadata dictionary+ content:+ application/json:+ schema:+ type: object+ additionalProperties:+ $ref: "#/components/schemas/GlobalSubgraphInfo"++ /api/global_subgraphs/{id}:+ get:+ operationId: getGlobalSubgraph+ tags: [subgraph]+ summary: Get a global subgraph with full data+ description: Returns the blueprint for a globally-registered subgraph, used by the frontend to materialize the subgraph node.+ parameters:+ - name: id+ in: path+ required: true+ schema:+ type: string+ description: Subgraph identifier+ responses:+ "200":+ description: Full subgraph data+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/GlobalSubgraphData"+ "404":+ description: Subgraph not found++ # ---------------------------------------------------------------------------+ # Node Replacements+ # ---------------------------------------------------------------------------+ /api/node_replacements:+ get:+ operationId: getNodeReplacements+ tags: [node]+ summary: Get node replacement mappings+ description: |+ Returns a dictionary mapping deprecated or replaced node class names+ to their replacement node information.+ responses:+ "200":+ description: Replacement mappings+ content:+ application/json:+ schema:+ type: object+ additionalProperties: true++ # ---------------------------------------------------------------------------+ # Internal (x-internal: true)+ # ---------------------------------------------------------------------------+ /internal/logs:+ get:+ operationId: getInternalLogs+ tags: [internal]+ summary: Get server logs as text+ description: Returns structured ComfyUI log entries from the in-memory log buffer.+ x-internal: true+ responses:+ "200":+ description: Log text+ content:+ text/plain:+ schema:+ type: string++ /internal/logs/raw:+ get:+ operationId: getInternalLogsRaw+ tags: [internal]+ summary: Get raw structured log entries+ description: Returns the raw ComfyUI log buffer as text, together with metadata about the current size limit.+ x-internal: true+ responses:+ "200":+ description: Structured log data+ content:+ application/json:+ schema:+ type: object+ properties:+ entries:+ type: array+ items:+ type: object+ properties:+ t:+ type: number+ description: Timestamp+ m:+ type: string+ description: Message+ size:+ type: object+ properties:+ cols:+ type: integer+ rows:+ type: integer++ /internal/logs/subscribe:+ patch:+ operationId: subscribeToLogs+ tags: [internal]+ summary: Subscribe or unsubscribe a WebSocket client to log streaming+ description: Subscribes or unsubscribes the current client from live log streaming over the WebSocket.+ x-internal: true+ requestBody:+ required: true+ content:+ application/json:+ schema:+ type: object+ required:+ - clientId+ - enabled+ properties:+ clientId:+ type: string+ description: WebSocket client ID+ enabled:+ type: boolean+ description: Enable or disable log streaming for this client+ responses:+ "200":+ description: Subscription updated++ /internal/folder_paths:+ get:+ operationId: getInternalFolderPaths+ tags: [internal]+ summary: Get configured folder paths+ description: Returns the filesystem paths ComfyUI is configured to load models and other assets from, keyed by folder type.+ x-internal: true+ responses:+ "200":+ description: Dictionary of folder type to paths+ content:+ application/json:+ schema:+ type: object+ additionalProperties:+ type: array+ items:+ type: array+ items:+ type: string+ description: Map of folder type name to list of [path, ...] entries++ /internal/files/{directory_type}:+ get:+ operationId: getInternalFiles+ tags: [internal]+ summary: List files in a directory type+ description: Lists the files present in one of ComfyUI's known directories (input, output, or temp).+ x-internal: true+ parameters:+ - name: directory_type+ in: path+ required: true+ schema:+ type: string+ description: Directory type (e.g. output, input, temp)+ responses:+ "200":+ description: Array of filenames+ content:+ application/json:+ schema:+ type: array+ items:+ type: string++ # ---------------------------------------------------------------------------+ # Assets (x-feature-gate: enable-assets)+ # ---------------------------------------------------------------------------+ /api/assets/hash/{hash}:+ head:+ operationId: checkAssetByHash+ tags: [assets]+ summary: Check if an asset with the given hash exists+ description: Returns 204 if an asset with the given content hash already exists, 404 otherwise. Used by clients to deduplicate uploads before transferring bytes.+ x-feature-gate: enable-assets+ parameters:+ - name: hash+ in: path+ required: true+ schema:+ type: string+ description: "Blake3 hash of the asset (e.g. blake3:abc123...)"+ responses:+ "200":+ description: Asset exists+ "404":+ description: No asset with this hash++ /api/assets:+ get:+ operationId: listAssets+ tags: [assets]+ summary: List assets with filtering and pagination+ description: Returns a paginated list of assets, optionally filtered by tags, name, or other query parameters.+ x-feature-gate: enable-assets+ parameters:+ - name: limit+ in: query+ schema:+ type: integer+ default: 50+ - name: offset+ in: query+ schema:+ type: integer+ default: 0+ - name: include_tags+ in: query+ schema:+ type: array+ items:+ type: string+ style: form+ explode: true+ description: Tags that assets must have (AND logic)+ - name: exclude_tags+ in: query+ schema:+ type: array+ items:+ type: string+ style: form+ explode: true+ description: Tags that assets must not have+ - name: name_contains+ in: query+ schema:+ type: string+ description: Filter assets whose name contains this substring+ - name: metadata_filter+ in: query+ schema:+ type: string+ description: JSON-encoded metadata key/value filter+ - name: sort+ in: query+ schema:+ type: string+ description: Field to sort by+ - name: order+ in: query+ schema:+ type: string+ enum: [asc, desc]+ description: Sort direction+ responses:+ "200":+ description: Asset list+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/ListAssetsResponse"+ post:+ operationId: createAsset+ tags: [assets]+ summary: Upload a new asset+ description: Uploads a new asset (binary content plus metadata) and registers it in the asset database.+ x-feature-gate: enable-assets+ requestBody:+ required: true+ content:+ multipart/form-data:+ schema:+ type: object+ required:+ - file+ properties:+ file:+ type: string+ format: binary+ description: Asset file to upload+ name:+ type: string+ description: Display name for the asset+ tags:+ type: string+ description: Comma-separated tags+ user_metadata:+ type: string+ description: JSON-encoded user metadata+ hash:+ type: string+ description: "Blake3 hash of the file content (e.g. blake3:abc123...)"+ mime_type:+ type: string+ description: MIME type of the file (overrides auto-detected type)+ preview_id:+ type: string+ format: uuid+ description: ID of an existing asset to use as the preview image+ responses:+ "201":+ description: Asset created+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/AssetCreated"++ /api/assets/from-hash:+ post:+ operationId: createAssetFromHash+ tags: [assets]+ summary: Create an asset reference from an existing hash+ description: Registers a new asset that references existing content by hash, without re-uploading the bytes.+ x-feature-gate: enable-assets+ requestBody:+ required: true+ content:+ application/json:+ schema:+ type: object+ required:+ - hash+ - name+ properties:+ hash:+ type: string+ description: Blake3 hash of existing content+ name:+ type: string+ description: Display name+ tags:+ type: array+ items:+ type: string+ user_metadata:+ type: object+ additionalProperties: true+ responses:+ "201":+ description: Asset created from hash+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/AssetCreated"++ /api/assets/{id}:+ get:+ operationId: getAsset+ tags: [assets]+ summary: Get asset metadata+ description: Returns the metadata for a single asset.+ x-feature-gate: enable-assets+ parameters:+ - name: id+ in: path+ description: The asset ID.+ required: true+ schema:+ type: string+ format: uuid+ responses:+ "200":+ description: Asset metadata+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/Asset"+ "404":+ description: Asset not found+ put:+ operationId: updateAsset+ tags: [assets]+ summary: Update asset metadata+ description: Updates the mutable metadata of an asset (name, tags, etc.). Binary content is immutable.+ x-feature-gate: enable-assets+ parameters:+ - name: id+ in: path+ description: The asset ID.+ required: true+ schema:+ type: string+ format: uuid+ requestBody:+ required: true+ content:+ application/json:+ schema:+ type: object+ properties:+ name:+ type: string+ description: New display name for the asset+ user_metadata:+ type: object+ additionalProperties: true+ description: Custom user metadata to set+ preview_id:+ type: string+ format: uuid+ description: ID of the asset to use as the preview+ responses:+ "200":+ description: Asset updated+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/AssetUpdated"+ delete:+ operationId: deleteAsset+ tags: [assets]+ summary: Delete an asset+ description: Removes an asset entry. Depending on the server configuration, the underlying content may also be deleted.+ x-feature-gate: enable-assets+ parameters:+ - name: id+ in: path+ description: The asset ID.+ required: true+ schema:+ type: string+ format: uuid+ - name: delete_content+ in: query+ schema:+ type: boolean+ description: Also delete the underlying content file+ responses:+ "204":+ description: Asset deleted++ /api/assets/{id}/content:+ get:+ operationId: getAssetContent+ tags: [assets]+ summary: Download asset file content+ description: Returns the binary content of an asset. Supports range requests.+ x-feature-gate: enable-assets+ parameters:+ - name: id+ in: path+ description: The asset ID.+ required: true+ schema:+ type: string+ format: uuid+ responses:+ "200":+ description: Asset file content+ content:+ application/octet-stream:+ schema:+ type: string+ format: binary+ "404":+ description: Asset not found++ /api/assets/{id}/tags:+ post:+ operationId: addAssetTags+ tags: [assets]+ summary: Add tags to an asset+ description: Adds one or more tags to an asset.+ x-feature-gate: enable-assets+ parameters:+ - name: id+ in: path+ description: The asset ID.+ required: true+ schema:+ type: string+ format: uuid+ requestBody:+ required: true+ content:+ application/json:+ schema:+ type: object+ required:+ - tags+ properties:+ tags:+ type: array+ items:+ type: string+ responses:+ "200":+ description: Tags added+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/TagsModificationResponse"+ delete:+ operationId: removeAssetTags+ tags: [assets]+ summary: Remove tags from an asset+ description: Removes one or more tags from an asset.+ x-feature-gate: enable-assets+ parameters:+ - name: id+ in: path+ description: The asset ID.+ required: true+ schema:+ type: string+ format: uuid+ requestBody:+ required: true+ content:+ application/json:+ schema:+ type: object+ required:+ - tags+ properties:+ tags:+ type: array+ items:+ type: string+ responses:+ "200":+ description: Tags removed+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/TagsModificationResponse"++ /api/tags:+ get:+ operationId: listTags+ tags: [assets]+ summary: List all known tags with counts+ description: Returns the list of all tags known to the asset database, with counts.+ x-feature-gate: enable-assets+ parameters:+ - name: limit+ in: query+ schema:+ type: integer+ - name: offset+ in: query+ schema:+ type: integer+ - name: search+ in: query+ schema:+ type: string+ description: Search term for tag name+ responses:+ "200":+ description: Tag list+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/ListTagsResponse"++ /api/assets/tags/refine:+ get:+ operationId: refineAssetTags+ tags: [assets]+ summary: Get tag counts for assets matching current filters+ description: Returns suggested additional tags that would refine a filtered asset query, together with the count of assets each tag would select.+ x-feature-gate: enable-assets+ parameters:+ - name: include_tags+ in: query+ schema:+ type: array+ items:+ type: string+ style: form+ explode: true+ description: Tags that assets must have (AND logic)+ - name: exclude_tags+ in: query+ schema:+ type: array+ items:+ type: string+ style: form+ explode: true+ description: Tags that assets must not have+ - name: name_contains+ in: query+ schema:+ type: string+ description: Filter assets whose name contains this substring+ - name: metadata_filter+ in: query+ schema:+ type: string+ description: JSON-encoded metadata key/value filter+ - name: limit+ in: query+ schema:+ type: integer+ - name: offset+ in: query+ schema:+ type: integer+ - name: sort+ in: query+ schema:+ type: string+ description: Field to sort by+ - name: order+ in: query+ schema:+ type: string+ enum: [asc, desc]+ description: Sort direction+ responses:+ "200":+ description: Tag histogram+ content:+ application/json:+ schema:+ $ref: "#/components/schemas/AssetTagHistogramResponse"++ /api/assets/seed:+ post:+ operationId: seedAssets+ tags: [assets]+ summary: Trigger asset scan/seed from filesystem+ description: Starts a background job that scans the configured directories and registers any assets not yet present in the asset database.+ x-feature-gate: enable-assets+ requestBody:+ required: false+ content:+ application/json:+ schema:+ type: object+ properties:+ roots:+ type: array+ items:+ type: string+ description: Root folder paths to scan (if omitted, scans all)+ responses:+ "200":+ description: Seed started+ content:+ application/json:+ schema:+ type: object+ properties:+ status:+ type: string++ /api/assets/seed/status:+ get:+ operationId: getAssetSeedStatus+ tags: [assets]+ summary: Get asset scan progress+ description: Returns the progress and status of the most recently-started asset seed job.+ x-feature-gate: enable-assets+ responses:+ "200":+ description: Scan progress+ content:+ application/json:+ schema:+ type: object+ additionalProperties: true+ description: Scan progress details (files scanned, total, status, etc.)++ /api/assets/seed/cancel:+ post:+ operationId: cancelAssetSeed+ tags: [assets]+ summary: Cancel an in-progress asset scan+ description: Requests cancellation of the currently-running asset seed job.+ x-feature-gate: enable-assets+ responses:+ "200":+ description: Scan cancelled+ content:+ application/json:+ schema:+ type: object+ properties:+ status:+ type: string++ /api/assets/prune:+ post:+ operationId: pruneAssets+ tags: [assets]+ summary: Mark assets whose backing files no longer exist on disk+ description: Starts a background job that removes asset entries whose underlying content no longer exists on disk.+ x-feature-gate: enable-assets+ responses:+ "200":+ description: Prune result+ content:+ application/json:+ schema:+ type: object+ properties:+ status:+ type: string+ marked:+ type: integer+ description: Number of assets marked as missing++components:+ parameters:+ ComfyUserHeader:+ name: Comfy-User+ in: header+ required: false+ schema:+ type: string+ description: |+ Identifies the active user in multi-user mode. Used for settings,+ userdata, and history isolation. This is not a security mechanism —+ it is an organisational convenience with no authentication behind it.++ schemas:+ # -------------------------------------------------------------------+ # Prompt+ # -------------------------------------------------------------------+ PromptRequest:+ type: object+ description: A workflow submission. Wraps the prompt graph plus optional client identifier and extra per-request data.+ required:+ - prompt+ properties:+ prompt:+ type: object+ description: |+ The workflow graph to execute. Keys are node IDs (strings);+ values are objects with class_type and inputs.+ 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 associated with the prompt (e.g. extra_pnginfo)+ additionalProperties: true+ client_id:+ type: string+ description: WebSocket client ID to receive progress updates+ prompt_id:+ type: string+ format: uuid+ description: "Client-supplied prompt ID. Server generates a UUID if omitted."+ partial_execution_targets:+ type: array+ items:+ type: string+ description: List of node IDs to execute (partial graph execution)++ PromptResponse:+ type: object+ description: Server acknowledgement of a workflow submission. Includes the assigned `prompt_id` and current queue position.+ 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: Validation errors keyed by node ID+ additionalProperties:+ $ref: "#/components/schemas/NodeError"+ error:+ description: Top-level prompt error (string message or structured error)+ oneOf:+ - type: string+ - $ref: "#/components/schemas/PromptError"++ PromptErrorResponse:+ type: object+ description: Error response when prompt validation fails+ additionalProperties: true++ PromptError:+ type: object+ description: Structured prompt validation error+ properties:+ type:+ type: string+ message:+ type: string+ details:+ type: string++ Error:+ type: object+ description: Detailed node-level error+ properties:+ type:+ type: string+ message:+ type: string+ details:+ type: string+ extra_info:+ type: object+ properties:+ input_name:+ type: string+ additionalProperties: true++ NodeError:+ type: object+ description: Error details for a single node+ properties:+ errors:+ type: array+ items:+ $ref: "#/components/schemas/Error"+ class_type:+ type: string+ description: The node's class type+ dependent_outputs:+ type: array+ items: {}++ PromptInfo:+ type: object+ description: Summary of a queued or recently-executed prompt, as returned by the queue and history endpoints.+ properties:+ exec_info:+ type: object+ properties:+ queue_remaining:+ type: integer+ description: Number of items remaining in the queue++ # -------------------------------------------------------------------+ # Queue+ # -------------------------------------------------------------------+ QueueInfo:+ type: object+ description: Queue information with pending and running items+ properties:+ queue_running:+ type: array+ description: Currently running queue items+ items:+ type: array+ description: |+ Queue item tuple: [number, prompt_id, prompt, extra_data, outputs_to_execute, sensitive]+ items: {}+ prefixItems:+ - type: number+ description: Priority number+ - type: string+ format: uuid+ description: prompt_id+ - type: object+ description: prompt graph+ additionalProperties: true+ - type: object+ description: extra_data+ additionalProperties: true+ - type: array+ description: outputs_to_execute (list of output node IDs)+ items:+ type: string+ - type: object+ description: sensitive data (may be omitted)+ additionalProperties: true+ queue_pending:+ type: array+ description: Pending queue items (oldest first)+ items:+ type: array+ description: |+ Queue item tuple: [number, prompt_id, prompt, extra_data, outputs_to_execute, sensitive]+ items: {}+ prefixItems:+ - type: number+ description: Priority number+ - type: string+ format: uuid+ description: prompt_id+ - type: object+ description: prompt graph+ additionalProperties: true+ - type: object+ description: extra_data+ additionalProperties: true+ - type: array+ description: outputs_to_execute (list of output node IDs)+ items:+ type: string+ - type: object+ description: sensitive data (may be omitted)+ additionalProperties: true++ QueueManageRequest:+ type: object+ description: Request to clear or delete from queue+ properties:+ clear:+ type: boolean+ description: If true, clear all pending items+ delete:+ type: array+ items:+ type: string+ description: Array of prompt IDs to delete from queue++ # -------------------------------------------------------------------+ # History+ # -------------------------------------------------------------------+ HistoryEntry:+ type: object+ description: A single execution history entry+ properties:+ prompt:+ type: array+ description: |+ Prompt tuple: [number, prompt_id, prompt_graph, extra_data, output_node_ids]+ items: {}+ outputs:+ type: object+ description: Output data from execution keyed by node ID+ additionalProperties: true+ status:+ type: object+ description: Execution status (status_str, completed, messages, etc.)+ additionalProperties: true+ meta:+ type: object+ description: Metadata about the execution and nodes+ additionalProperties: true++ HistoryManageRequest:+ type: object+ description: Request to clear or delete history entries+ properties:+ clear:+ type: boolean+ description: If true, clear all history+ delete:+ type: array+ items:+ type: string+ description: Array of prompt IDs to delete from history++ # -------------------------------------------------------------------+ # Jobs+ # -------------------------------------------------------------------+ JobEntry:+ type: object+ description: Lightweight job data for list views+ required:+ - id+ - status+ properties:+ id:+ type: string+ format: uuid+ description: Unique job identifier (same as prompt_id)+ status:+ type: string+ description: Current job status+ create_time:+ type: number+ description: Job creation timestamp+ execution_start_time:+ type: number+ description: Workflow execution start timestamp+ execution_end_time:+ type: number+ description: Workflow execution end timestamp+ preview_output:+ type: object+ additionalProperties: true+ description: Primary preview output+ outputs_count:+ type: integer+ description: Total number of output files++ JobDetailResponse:+ type: object+ description: Full job details including workflow and outputs+ required:+ - id+ - status+ properties:+ id:+ type: string+ format: uuid+ status:+ type: string+ workflow:+ type: object+ additionalProperties: true+ description: Full ComfyUI workflow+ outputs:+ type: object+ additionalProperties: true+ description: Full outputs object from execution+ execution_error:+ $ref: "#/components/schemas/ExecutionError"+ create_time:+ type: number+ update_time:+ type: number+ execution_start_time:+ type: number+ execution_end_time:+ type: number+ preview_output:+ type: object+ additionalProperties: true+ outputs_count:+ type: integer+ execution_status:+ type: object+ additionalProperties: true+ execution_meta:+ type: object+ additionalProperties: true++ ExecutionError:+ type: object+ description: Detailed execution error from ComfyUI+ properties:+ node_id:+ type: string+ description: ID of the node that failed+ node_type:+ type: string+ description: Type name of the node+ exception_message:+ type: string+ description: Human-readable error message+ exception_type:+ type: string+ description: Python exception type+ traceback:+ type: array+ items:+ type: string+ description: Traceback lines+ current_inputs:+ type: object+ additionalProperties: true+ current_outputs:+ type: object+ additionalProperties: true++ PaginationInfo:+ type: object+ description: Pagination metadata returned alongside list responses.+ properties:+ offset:+ type: integer+ limit:+ type: integer+ total:+ type: integer+ has_more:+ type: boolean++ # -------------------------------------------------------------------+ # Upload / View+ # -------------------------------------------------------------------+ UploadResult:+ type: object+ description: Response body returned by the image/mask upload endpoints, describing where the uploaded file now lives.+ properties:+ name:+ type: string+ description: Saved filename (may be renamed to avoid collisions)+ subfolder:+ type: string+ description: Subfolder the file was saved to+ type:+ type: string+ description: Directory type (input, temp)++ # -------------------------------------------------------------------+ # System+ # -------------------------------------------------------------------+ DeviceStats:+ type: object+ description: GPU/compute device statistics+ required:+ - name+ - type+ - index+ properties:+ name:+ type: string+ description: Device name+ type:+ type: string+ description: Device type (cuda, mps, cpu, etc.)+ index:+ type: number+ 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 PyTorch-managed VRAM in bytes+ torch_vram_free:+ type: number+ description: Free PyTorch-managed VRAM in bytes++ SystemStatsResponse:+ type: object+ description: Hardware, VRAM, Python, and ComfyUI version information for the running process.+ required:+ - system+ - devices+ properties:+ system:+ type: object+ required:+ - os+ - python_version+ - embedded_python+ - comfyui_version+ - pytorch_version+ - argv+ - ram_total+ - ram_free+ properties:+ os:+ type: string+ description: Operating system+ python_version:+ type: string+ description: Python version+ embedded_python:+ type: boolean+ description: Whether using embedded Python+ comfyui_version:+ type: string+ description: ComfyUI version string+ pytorch_version:+ type: string+ description: PyTorch version+ required_frontend_version:+ type: string+ description: Required frontend version+ argv:+ type: array+ items:+ type: string+ description: Command line arguments+ ram_total:+ type: number+ description: Total RAM in bytes+ ram_free:+ type: number+ description: Free RAM in bytes+ installed_templates_version:+ type: string+ nullable: true+ description: Version of the currently installed workflow templates+ required_templates_version:+ type: string+ nullable: true+ description: Minimum required workflow templates version for this ComfyUI build+ devices:+ type: array+ items:+ $ref: "#/components/schemas/DeviceStats"++ # -------------------------------------------------------------------+ # Node / Object Info+ # -------------------------------------------------------------------+ NodeInfo:+ type: object+ description: 'Definition of a registered node class: its inputs, outputs, category, and display metadata.'+ properties:+ input:+ type: object+ description: Input specifications (required and optional groups)+ additionalProperties: true+ input_order:+ type: object+ description: Ordered input names per group+ additionalProperties:+ type: array+ items:+ type: string+ output:+ type: array+ items:+ type: string+ description: Output type names+ output_is_list:+ type: array+ items:+ type: boolean+ description: Whether each output is a list+ output_name:+ type: array+ items:+ type: string+ description: Display names of outputs+ name:+ type: string+ description: Internal class name+ display_name:+ type: string+ description: Human-readable display name+ description:+ type: string+ description: Node description+ python_module:+ type: string+ description: Python module implementing the node+ category:+ type: string+ description: Node category path+ output_node:+ type: boolean+ description: Whether this is an output node+ output_tooltips:+ type: array+ items:+ type: string+ description: Tooltips for each output+ 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+ is_input_list:+ type: boolean+ description: Whether the node accepts list inputs+ dev_only:+ type: boolean+ description: Whether the node is developer-only (hidden in production UI)+ has_intermediate_output:+ type: boolean+ description: Whether the node emits intermediate output during execution+ search_aliases:+ type: array+ items:+ type: string+ description: Alternative search terms for finding this node+ essentials_category:+ type: string+ description: Category override used by the essentials pack++ # -------------------------------------------------------------------+ # Models+ # -------------------------------------------------------------------+ ModelFolder:+ type: object+ description: A configured model folder and the list of disk paths it resolves to.+ required:+ - name+ - folders+ properties:+ name:+ type: string+ description: Model folder type name (e.g. "checkpoints")+ folders:+ type: array+ items:+ type: string+ description: Filesystem paths for this model type++ ModelFile:+ type: object+ description: A single model file in a folder, with filesystem metadata.+ required:+ - name+ - pathIndex+ properties:+ name:+ type: string+ description: Model filename+ pathIndex:+ type: integer+ description: Index into the folder's paths array+ modified:+ type: number+ description: File modification timestamp+ created:+ type: number+ description: File creation timestamp+ size:+ type: integer+ format: int64+ description: File size in bytes++ # -------------------------------------------------------------------+ # Subgraphs+ # -------------------------------------------------------------------+ GlobalSubgraphInfo:+ type: object+ description: Metadata for a global subgraph blueprint (without full data)+ required:+ - source+ - name+ - info+ properties:+ source:+ type: string+ description: Source type ("templates" or "custom_node")+ name:+ type: string+ description: Display name of the subgraph blueprint+ info:+ type: object+ description: Additional information about the subgraph+ required:+ - node_pack+ properties:+ node_pack:+ type: string+ description: The node pack/module providing this subgraph+ data:+ type: string+ description: The full subgraph JSON data (may be empty in list view)++ GlobalSubgraphData:+ type: object+ description: Full data for a global subgraph blueprint+ required:+ - source+ - name+ - info+ - data+ properties:+ source:+ type: string+ description: Source type ("templates" or "custom_node")+ name:+ type: string+ description: Display name of the subgraph blueprint+ info:+ type: object+ description: Additional information about the subgraph+ required:+ - node_pack+ properties:+ node_pack:+ type: string+ description: The node pack/module providing this subgraph+ data:+ type: string+ description: The full subgraph JSON data as a string++ # -------------------------------------------------------------------+ # Userdata+ # -------------------------------------------------------------------+ UserDataResponse:+ description: |+ Response body for the POST endpoints `/api/userdata/{file}` and+ `/api/userdata/{file}/move/{dest}`. Returns a single item whose+ shape depends on the `full_info` query parameter.+ x-variant-selector:+ full_info=true: file-info object (`GetUserDataResponseFullFile`)+ default: relative path string+ oneOf:+ - $ref: "#/components/schemas/GetUserDataResponseFullFile"+ - type: string+ description: Relative path of the written or moved file. Returned when `full_info` is absent or false.++ ListUserdataResponse:+ description: |+ Response body for `GET /api/userdata`. The array item shape is+ determined by the `full_info` and `split` query parameters.+ x-variant-selector:+ full_info=true: array of file-info objects (`GetUserDataResponseFullFile`)+ split=true: array of `[relative_path, ...path_components]` arrays+ default: array of relative path strings+ oneOf:+ - type: array+ items:+ $ref: "#/components/schemas/GetUserDataResponseFullFile"+ description: Returned when `full_info=true`.+ - type: array+ items:+ type: array+ items:+ type: string+ minItems: 2+ description: |+ Returned when `split=true` and `full_info=false`. Each inner+ array is `[relative_path, ...path_components]`.+ - type: array+ items:+ type: string+ description: Default shape — array of file paths relative to the user data root.++ GetUserDataResponseFullFile:+ type: object+ description: A single entry in a full-info user data listing.+ properties:+ path:+ type: string+ description: File name or path relative to the user directory+ created:+ type: number+ description: Unix timestamp of file creation+ size:+ type: integer+ description: File size in bytes+ modified:+ type: integer+ format: int64+ description: Unix timestamp of last modification in milliseconds++ # -------------------------------------------------------------------+ # Assets+ # -------------------------------------------------------------------+ Asset:+ type: object+ description: A registered asset — an input/output file tracked in the asset database with content hash and metadata.+ required:+ - id+ - name+ - size+ - created_at+ - updated_at+ properties:+ id:+ type: string+ format: uuid+ description: Unique identifier for the asset+ name:+ type: string+ description: Name of the asset file+ asset_hash:+ type: string+ description: Blake3 hash of the asset content+ pattern: "^blake3:[a-f0-9]{64}$"+ size:+ type: integer+ format: int64+ description: Size of the asset in bytes+ mime_type:+ type: string+ description: MIME type of the asset+ tags:+ type: array+ items:+ type: string+ description: Tags associated with the asset+ user_metadata:+ type: object+ description: Custom user metadata+ additionalProperties: true+ metadata:+ type: object+ description: System-managed metadata (read-only)+ additionalProperties: true+ readOnly: true+ preview_url:+ type: string+ format: uri+ description: URL for asset preview/thumbnail+ preview_id:+ type: string+ format: uuid+ description: ID of the preview asset if available+ prompt_id:+ type: string+ format: uuid+ description: ID of the prompt that created this asset+ created_at:+ type: string+ format: date-time+ updated_at:+ type: string+ format: date-time+ last_access_time:+ type: string+ format: date-time+ is_immutable:+ type: boolean+ description: Whether this asset is immutable++ AssetCreated:+ description: Response body returned after successfully registering a new asset.+ allOf:+ - $ref: "#/components/schemas/Asset"+ - type: object+ required:+ - created_new+ properties:+ created_new:+ type: boolean+ description: Whether this was a new creation (true) or returned existing (false)++ AssetUpdated:+ type: object+ description: Response body returned after updating an asset's metadata.+ required:+ - id+ - updated_at+ properties:+ id:+ type: string+ format: uuid+ name:+ type: string+ asset_hash:+ type: string+ pattern: "^blake3:[a-f0-9]{64}$"+ tags:+ type: array+ items:+ type: string+ mime_type:+ type: string+ user_metadata:+ type: object+ additionalProperties: true+ updated_at:+ type: string+ format: date-time++ ListAssetsResponse:+ type: object+ description: Paginated list of assets.+ required:+ - assets+ - total+ - has_more+ properties:+ assets:+ type: array+ items:+ $ref: "#/components/schemas/Asset"+ total:+ type: integer+ has_more:+ type: boolean++ TagInfo:+ type: object+ description: A tag known to the asset database, with the number of assets bearing it.+ required:+ - name+ - count+ properties:+ name:+ type: string+ count:+ type: integer++ ListTagsResponse:+ type: object+ description: Flat list of all tags, with counts.+ required:+ - tags+ - total+ - has_more+ properties:+ tags:+ type: array+ items:+ $ref: "#/components/schemas/TagInfo"+ total:+ type: integer+ has_more:+ type: boolean++ AssetTagHistogramResponse:+ type: object+ description: Tags that would refine a filtered asset query, with the count of assets each tag would additionally select.+ required:+ - tag_counts+ properties:+ tag_counts:+ type: object+ additionalProperties:+ type: integer+ description: Map of tag names to occurrence counts++ TagsModificationResponse:+ type: object+ description: Response body returned after adding or removing tags on an asset.+ required:+ - total_tags+ properties:+ added:+ type: array+ items:+ type: string+ description: Tags successfully added+ removed:+ type: array+ items:+ type: string+ description: Tags successfully removed+ already_present:+ type: array+ items:+ type: string+ description: Tags already present (for add)+ not_present:+ type: array+ items:+ type: string+ description: Tags not present (for remove)+ total_tags:+ type: array+ items:+ type: string+ description: All tags on the asset after the operation++ # -------------------------------------------------------------------+ # Result / Output types+ # -------------------------------------------------------------------+ ResultItem:+ type: object+ description: A single output file reference+ properties:+ filename:+ type: string+ subfolder:+ type: string+ type:+ type: string+ enum: [input, output, temp]+ display_name:+ type: string++ NodeOutputs:+ type: object+ description: |+ Outputs from a single node execution. Known keys are listed below,+ but custom nodes may add arbitrary keys (additionalProperties).+ properties:+ images:+ type: array+ items:+ $ref: "#/components/schemas/ResultItem"+ audio:+ type: array+ items:+ $ref: "#/components/schemas/ResultItem"+ video:+ type: array+ items:+ $ref: "#/components/schemas/ResultItem"+ animated:+ type: array+ items:+ type: boolean+ text:+ oneOf:+ - type: string+ - type: array+ items:+ type: string+ additionalProperties: true++ TerminalSize:+ type: object+ description: Terminal dimensions+ properties:+ cols:+ type: number+ row:+ type: number++ LogEntry:+ type: object+ description: A single log entry+ properties:+ t:+ type: string+ description: Timestamp+ m:+ type: string+ description: Log message++ StatusWsMessageStatus:+ type: object+ description: Inner payload of a `status` WebSocket message, describing the execution queue state.+ properties:+ exec_info:+ type: object+ required:+ - queue_remaining+ properties:+ queue_remaining:+ type: integer++ StatusWsMessage:+ type: object+ description: Initial status message sent on connect + queue status updates+ properties:+ status:+ $ref: "#/components/schemas/StatusWsMessageStatus"+ sid:+ type: string+ description: Session ID assigned by the server++ ProgressWsMessage:+ type: object+ description: Node execution progress (step N of M)+ required:+ - value+ - max+ - prompt_id+ - node+ properties:+ value:+ type: integer+ description: Current step+ max:+ type: integer+ description: Total steps+ prompt_id:+ type: string+ node:+ type: string+ description: Node ID currently executing++ ProgressTextWsMessage:+ type: object+ description: Text-based progress update from a node+ properties:+ nodeId:+ type: string+ text:+ type: string+ prompt_id:+ type: string++ NodeProgressState:+ type: object+ description: Progress state for a single node+ properties:+ value:+ type: number+ max:+ type: number+ state:+ type: string+ enum: [pending, running, finished, error]+ node_id:+ type: string+ prompt_id:+ type: string+ display_node_id:+ type: string+ parent_node_id:+ type: string+ real_node_id:+ type: string++ ProgressStateWsMessage:+ type: object+ description: Bulk progress state for all nodes in a prompt+ required:+ - prompt_id+ - nodes+ properties:+ prompt_id:+ type: string+ nodes:+ type: object+ description: Map of node ID to progress state+ additionalProperties:+ $ref: "#/components/schemas/NodeProgressState"++ ExecutingWsMessage:+ type: object+ description: Fired when a node begins execution+ required:+ - node+ - display_node+ - prompt_id+ properties:+ node:+ type: string+ description: Node ID+ display_node:+ type: string+ description: Display node ID (may differ for subgraphs)+ prompt_id:+ type: string++ ExecutedWsMessage:+ type: object+ description: Fired when a node completes execution with output+ required:+ - node+ - display_node+ - prompt_id+ - output+ properties:+ node:+ type: string+ display_node:+ type: string+ prompt_id:+ type: string+ output:+ $ref: "#/components/schemas/NodeOutputs"+ merge:+ type: boolean+ description: Whether to merge with existing output++ ExecutionWsMessageBase:+ type: object+ description: Base fields for execution lifecycle messages+ required:+ - prompt_id+ - timestamp+ properties:+ prompt_id:+ type: string+ timestamp:+ type: integer+ description: Unix timestamp in milliseconds++ ExecutionStartWsMessage:+ allOf:+ - $ref: "#/components/schemas/ExecutionWsMessageBase"+ description: Fired when prompt execution begins++ ExecutionSuccessWsMessage:+ allOf:+ - $ref: "#/components/schemas/ExecutionWsMessageBase"+ description: Fired when prompt execution completes successfully++ ExecutionCachedWsMessage:+ allOf:+ - $ref: "#/components/schemas/ExecutionWsMessageBase"+ - type: object+ properties:+ nodes:+ type: array+ items:+ type: string+ description: List of node IDs that were cached+ description: Fired when nodes are served from cache++ ExecutionInterruptedWsMessage:+ allOf:+ - $ref: "#/components/schemas/ExecutionWsMessageBase"+ - type: object+ properties:+ node_id:+ type: string+ node_type:+ type: string+ executed:+ type: array+ items:+ type: string+ description: Node IDs that completed before interruption+ description: Fired when execution is interrupted by user++ ExecutionErrorWsMessage:+ allOf:+ - $ref: "#/components/schemas/ExecutionWsMessageBase"+ - type: object+ properties:+ node_id:+ type: string+ node_type:+ type: string+ executed:+ type: array+ items:+ type: string+ exception_message:+ type: string+ exception_type:+ type: string+ traceback:+ type: array+ items:+ type: string+ current_inputs: {}+ current_outputs: {}+ description: Fired when a node throws an exception during execution++ LogsWsMessage:+ type: object+ description: Streaming log entries from the server+ properties:+ size:+ $ref: "#/components/schemas/TerminalSize"+ entries:+ type: array+ items:+ $ref: "#/components/schemas/LogEntry"++ NotificationWsMessage:+ type: object+ description: Server notification (e.g. model download complete)+ properties:+ value:+ type: string+ id:+ type: string++ FeatureFlagsWsMessage:+ type: object+ description: Feature flags sent on connect+ additionalProperties: true++ AssetDownloadWsMessage:+ type: object+ description: Asset download progress+ required:+ - task_id+ - asset_name+ - bytes_total+ - bytes_downloaded+ - progress+ - status+ properties:+ task_id:+ type: string+ asset_name:+ type: string+ bytes_total:+ type: number+ bytes_downloaded:+ type: number+ progress:+ type: number+ description: 0.0 to 1.0+ status:+ type: string+ enum: [created, running, completed, failed]+ asset_id:+ type: string+ error:+ type: string++ AssetExportWsMessage:+ type: object+ description: Bulk asset export progress+ required:+ - task_id+ - assets_total+ - assets_attempted+ - assets_failed+ - bytes_total+ - bytes_processed+ - progress+ - status+ properties:+ task_id:+ type: string+ export_name:+ type: string+ assets_total:+ type: number+ assets_attempted:+ type: number+ assets_failed:+ type: number+ bytes_total:+ type: number+ bytes_processed:+ type: number+ progress:+ type: number+ description: 0.0 to 1.0+ status:+ type: string+ enum: [created, running, completed, failed]+ error:+ type: string