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: 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) 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 `/api/userdata` — either a list of filenames or a list of full file objects, depending on the `full_info` query parameter. oneOf: - $ref: "#/components/schemas/UserDataResponseFull" - $ref: "#/components/schemas/UserDataResponseShort" UserDataResponseFull: type: object description: List of files in the authenticated user's data directory, as full file objects with metadata. 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 description: List of files in the authenticated user's data directory, as filename strings only. 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