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 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 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 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 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 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 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 parameters: - name: job_id in: path 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 description: | 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 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 parameters: - $ref: "#/components/parameters/ComfyUserHeader" - name: prompt_id in: path 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 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 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 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) 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 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 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 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 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 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 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) 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 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: oneOf: - type: array items: type: string description: Simple filename list - type: array items: $ref: "#/components/schemas/GetUserDataResponseFullFile" description: Full file info list (when full_info=true) "404": description: Directory not found /api/v2/userdata: get: operationId: listUserdataV2 tags: [userdata] summary: List files in userdata (v2 format) 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 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 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 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 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 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) 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 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 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 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 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 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 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 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 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 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 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 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 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 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 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 x-feature-gate: enable-assets parameters: - name: id in: path 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 x-feature-gate: enable-assets parameters: - name: id in: path 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 x-feature-gate: enable-assets parameters: - name: id in: path 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 x-feature-gate: enable-assets parameters: - name: id in: path 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 x-feature-gate: enable-assets parameters: - name: id in: path 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 x-feature-gate: enable-assets parameters: - name: id in: path 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 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 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 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 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 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 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 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 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 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 properties: offset: type: integer limit: type: integer total: type: integer has_more: type: boolean # ------------------------------------------------------------------- # Upload / View # ------------------------------------------------------------------- UploadResult: type: object 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 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 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 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 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: oneOf: - $ref: "#/components/schemas/UserDataResponseFull" - $ref: "#/components/schemas/UserDataResponseShort" UserDataResponseFull: type: object properties: path: type: string size: type: integer modified: type: integer format: int64 description: Unix timestamp of last modification in milliseconds created: type: number description: Unix timestamp of file creation UserDataResponseShort: type: string GetUserDataResponseFullFile: type: object 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 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: 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 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 required: - assets - total - has_more properties: assets: type: array items: $ref: "#/components/schemas/Asset" total: type: integer has_more: type: boolean TagInfo: type: object required: - name - count properties: name: type: string count: type: integer ListTagsResponse: type: object required: - tags - total - has_more properties: tags: type: array items: $ref: "#/components/schemas/TagInfo" total: type: integer has_more: type: boolean AssetTagHistogramResponse: type: object required: - tag_counts properties: tag_counts: type: object additionalProperties: type: integer description: Map of tag names to occurrence counts TagsModificationResponse: type: object 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 TaskOutput: type: object description: Outputs from a full task, keyed by node ID additionalProperties: $ref: "#/components/schemas/NodeOutputs" # ------------------------------------------------------------------- # REST response types # ------------------------------------------------------------------- EmbeddingsResponse: type: array description: List of available embedding names items: type: string ExtensionsResponse: type: array description: List of frontend extension JS file URLs items: type: string 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 LogRawResponse: type: object description: Response from /api/logs/raw properties: size: $ref: "#/components/schemas/TerminalSize" entries: type: array items: $ref: "#/components/schemas/LogEntry" UserInfo: type: object description: User mode and storage information properties: storage: type: string enum: [server] migrated: type: boolean description: Only present in single-user mode users: type: object description: Only present in multi-user mode — map of user ID to username additionalProperties: type: string UserDataFullInfo: type: object description: Full metadata for a userdata file properties: path: type: string size: type: number modified: type: number description: Unix timestamp of last modification created: type: number description: Unix timestamp of file creation # ------------------------------------------------------------------- # WebSocket message schemas # ------------------------------------------------------------------- StatusWsMessageStatus: type: object 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