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)

- name: auth

description: Authentication and session management (cloud-only)

- name: billing

description: Billing, subscriptions, and payment management (cloud-only)

- name: workspace

description: Workspace and team management (cloud-only)

- name: hub

description: "ComfyUI Hub: profiles, shared workflows, and labels (cloud-only)"

- name: workflows

description: Cloud workflow management and versioning (cloud-only)

- name: task

description: Background task management (cloud-only)

- name: runtime-only

description: Operations served exclusively by the cloud runtime with no local equivalent

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. Cloud deployments may include additional typed fields alongside the boolean flags.

responses:

"200":

description: Feature flags

content:

application/json:

schema:

type: object

additionalProperties:

type: boolean

properties:

max_upload_size:

type: integer

format: int64

minimum: 0

description: "Maximum file upload size in bytes."

free_tier_credits:

type: integer

format: int32

minimum: 0

nullable: true

x-runtime: [cloud]

description: "[cloud-only] Credits available to free-tier users. Local ComfyUI returns null."

posthog_api_host:

type: string

format: uri

nullable: true

x-runtime: [cloud]

description: "[cloud-only] PostHog analytics proxy URL for frontend telemetry. Local ComfyUI returns null."

max_concurrent_jobs:

type: integer

format: int32

minimum: 0

nullable: true

x-runtime: [cloud]

description: "[cloud-only] Maximum concurrent jobs the authenticated user can run. Local ComfyUI returns null."

workflow_templates_version:

type: string

nullable: true

x-runtime: [cloud]

description: "[cloud-only] Version identifier for the workflow templates bundle. Local ComfyUI returns null."

workflow_templates_source:

type: string

nullable: true

enum: [dynamic_config_override, workflow_templates_version_json]

x-runtime: [cloud]

description: "[cloud-only] How the templates version was resolved. Local ComfyUI returns null."

# ---------------------------------------------------------------------------

# Node / Object Info

# ---------------------------------------------------------------------------

/api/object_info:

get:

operationId: getObjectInfo

tags: [node]

summary: Get all node definitions

description: |

Returns a dictionary of every registered node class, keyed by class name.

Each value is a NodeInfo object describing inputs, outputs, category, etc.

responses:

"200":

description: All node definitions

content:

application/json:

schema:

type: object

additionalProperties:

$ref: "#/components/schemas/NodeInfo"

/api/object_info/{node_class}:

get:

operationId: getObjectInfoByClass

tags: [node]

summary: Get a single node definition

description: Returns the `NodeInfo` definition for a single registered node class.

parameters:

- name: node_class

in: path

required: true

schema:

type: string

description: Node class name (e.g. "KSampler")

responses:

"200":

description: Single node definition

content:

application/json:

schema:

type: object

additionalProperties:

$ref: "#/components/schemas/NodeInfo"

"404":

description: Node class not found

/api/embeddings:

get:

operationId: getEmbeddings

tags: [node]

summary: List available embedding names

description: Returns the list of text-encoder embeddings available on disk.

responses:

"200":

description: Embedding names

content:

application/json:

schema:

type: array

items:

type: string

# ---------------------------------------------------------------------------

# Models

# ---------------------------------------------------------------------------

/api/models:

get:

operationId: getModelTypes

tags: [model]

summary: List model folder type names

description: Returns an array of model type names (e.g. checkpoints, loras, vae).

responses:

"200":

description: Model type names

content:

application/json:

schema:

type: array

items:

type: string

/api/models/{folder}:

get:

operationId: getModelsByFolder

tags: [model]

summary: List model filenames in a folder

description: Returns the names of model files in the given folder. This endpoint predates `/api/experiment/models/{folder}` and returns names only — prefer the experiment endpoint for new integrations.

parameters:

- name: folder

in: path

required: true

schema:

type: string

description: Model folder type name

responses:

"200":

description: Model filenames

content:

application/json:

schema:

type: array

items:

type: string

"404":

description: Unknown folder type

/api/experiment/models:

get:

operationId: getExperimentModels

tags: [model]

summary: List model folders with paths

description: Returns an array of model folder objects with name and folder paths.

responses:

"200":

description: Model folders

content:

application/json:

schema:

type: array

items:

$ref: "#/components/schemas/ModelFolder"

/api/experiment/models/{folder}:

get:

operationId: getExperimentModelsByFolder

tags: [model]

summary: List model files with metadata

description: Returns the model files in the given folder with richer metadata (path index, mtime, size) than the legacy `/api/models/{folder}` endpoint.

parameters:

- name: folder

in: path

required: true

schema:

type: string

description: Model folder type name

responses:

"200":

description: Model files with metadata

content:

application/json:

schema:

type: array

items:

$ref: "#/components/schemas/ModelFile"

"404":

description: Unknown folder type

/api/experiment/models/preview/{folder}/{path_index}/{filename}:

get:

operationId: getModelPreview

tags: [model]

summary: Get model preview image

description: Returns the preview image associated with a model file, if one exists alongside the model on disk.

parameters:

- name: folder

in: path

required: true

schema:

type: string

description: Model folder type name

- name: path_index

in: path

required: true

schema:

type: integer

description: Path index within the folder

- name: filename

in: path

required: true

schema:

type: string

description: Model filename

responses:

"200":

description: Preview image (WebP)

content:

image/webp:

schema:

type: string

format: binary

"404":

description: Preview not found

# ---------------------------------------------------------------------------

# Users

# ---------------------------------------------------------------------------

/api/users:

get:

operationId: getUsers

tags: [user]

summary: Get user storage info

description: |

Returns user storage configuration. In single-user mode returns

`{"storage": "server", "migrated": true/false}`. In multi-user mode

returns `{"storage": "server", "users": {"user_id": "user_dir", ...}}`.

parameters:

- $ref: "#/components/parameters/ComfyUserHeader"

responses:

"200":

description: User info

content:

application/json:

schema:

type: object

properties:

storage:

type: string

description: Storage backend type (always "server")

migrated:

type: boolean

description: Whether migration from browser storage is complete (single-user)

users:

type: object

additionalProperties:

type: string

description: Map of user_id to directory name (multi-user)

post:

operationId: createUser

tags: [user]

summary: Create a new user (multi-user mode)

description: Creates a new user entry. Only meaningful when ComfyUI is running in multi-user mode.

parameters:

- $ref: "#/components/parameters/ComfyUserHeader"

requestBody:

required: true

content:

application/json:

schema:

type: object

required:

- username

properties:

username:

type: string

description: Username for the new user

responses:

"200":

description: Created user ID

content:

application/json:

schema:

type: string

description: The generated user_id

"400":

description: Username already exists or invalid

# ---------------------------------------------------------------------------

# Userdata

# ---------------------------------------------------------------------------

/api/userdata:

get:

operationId: listUserdata

tags: [userdata]

summary: List files in a userdata directory

description: Lists files in the authenticated user's data directory. Returns either filename strings or full objects depending on the `full_info` query parameter.

parameters:

- $ref: "#/components/parameters/ComfyUserHeader"

- name: dir

in: query

required: true

schema:

type: string

description: Directory path relative to the user's data folder

- name: recurse

in: query

schema:

type: boolean

description: Recurse into subdirectories

- name: full_info

in: query

schema:

type: boolean

description: Return full file info objects instead of just names

- name: split

in: query

schema:

type: boolean

description: Split paths into directory components

responses:

"200":

description: File listing

content:

application/json:

schema:

$ref: "#/components/schemas/ListUserdataResponse"

"404":

description: Directory not found

/api/v2/userdata:

get:

operationId: listUserdataV2

tags: [userdata]

summary: List files in userdata (v2 format)

description: Lists files in the authenticated user's data directory using the v2 response shape, which always returns full objects.

parameters:

- $ref: "#/components/parameters/ComfyUserHeader"

- name: path

in: query

schema:

type: string

description: Directory path relative to user data root

responses:

"200":

description: File listing with metadata