Comfy-Org / ComfyUI
127,111 PythonThe most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface.
ComfyUI Specification
Located in openapi.yaml on branch HEAD
3.x (YAML)
YAML
229.9 KB
Raw YAML Specification
components:
schemas:
Asset:
description: Represents a user-owned asset (image, video, or other generated output).
properties:
created_at:
description: Timestamp when the asset was created
format: date-time
type: string
display_name:
description: Display name of the asset. Mirrors name for backwards compatibility.
nullable: true
type: string
file_path:
description: Relative path in global-namespace-root form (e.g. "models/checkpoints/flux.safetensors")
nullable: true
type: string
hash:
description: Blake3 hash of the asset content.
pattern: ^blake3:[a-f0-9]{64}$
type: string
id:
description: Unique identifier for the asset
format: uuid
type: string
is_immutable:
description: Whether this asset is immutable (cannot be modified or deleted)
type: boolean
job_id:
description: ID of the job that created this asset, if available
format: uuid
nullable: true
type: string
last_access_time:
description: Timestamp when the asset was last accessed
format: date-time
type: string
loader_path:
description: The bare value a loader widget consumes for this asset. For models it is the path inside the category folder (e.g. "flux.safetensors" for "models/checkpoints/flux.safetensors"), which is what the model resolver matches. For input/output/temp it is the content hash, because those assets are fetched by hash rather than staged by name — that is the value LoadImage-style widgets must carry. Clients add the "[output]"/"[temp]" annotation from the asset's own type, so it is never included here. Null when no such value can be derived.
nullable: true
type: string
metadata:
additionalProperties: true
description: System-managed metadata from download sources (HuggingFace, CivitAI, etc.) - read-only, not user-modifiable
readOnly: true
type: object
mime_type:
description: MIME type of the asset
type: string
name:
description: Name of the asset file
type: string
preview_id:
description: ID of the preview asset if available
format: uuid
nullable: true
type: string
preview_url:
description: URL for asset preview/thumbnail
format: uri
type: string
short_url:
description: Durable, owner-gated short link to this asset's content (relative `/api/s/{id}` path). Stable across the underlying signed URL's expiry — resolving it re-mints a fresh signed URL on every request — so it is safe to persist or share into chat, unlike `preview_url`. Only the minting user can resolve it. Omitted when the short-link surface is disabled or the asset has no resolvable content hash.
nullable: true
type: string
x-runtime:
- cloud
size:
description: Size of the asset in bytes
format: int64
type: integer
tags:
description: Tags associated with the asset
items:
type: string
type: array
updated_at:
description: Timestamp when the asset was last updated
format: date-time
type: string
user_metadata:
additionalProperties: true
description: Custom user metadata for the asset
type: object
required:
- id
- name
- created_at
- updated_at
type: object
AssetCreated:
allOf:
- $ref: '#/components/schemas/Asset'
- properties:
created_new:
description: Whether this was a new asset creation (true) or returned existing (false)
type: boolean
required:
- created_new
type: object
description: Response returned when a new asset is successfully created.
AssetInfo:
description: Lightweight asset reference used in workflow publishing payloads.
properties:
id:
description: Asset identifier.
type: string
in_library:
description: Whether the caller already owns this asset.
type: boolean
model:
description: Whether this asset is a model.
type: boolean
name:
type: string
preview_url:
description: Signed URL for previewing the asset.
type: string
public:
description: Whether this is a public (platform-provided) asset.
type: boolean
storage_url:
type: string
required:
- id
- name
- preview_url
- storage_url
- model
- public
- in_library
type: object
AssetTagHistogramResponse:
description: Histogram of tag counts used for refining asset search results.
properties:
tag_counts:
additionalProperties:
type: integer
description: Map of tag names to their occurrence counts on matching assets
example:
checkpoint: 32
lora: 193
vae: 6
type: object
required:
- tag_counts
type: object
AssetUpdated:
description: Response returned when an existing asset is successfully updated.
properties:
display_name:
description: Display name of the asset. Mirrors name for backwards compatibility.
nullable: true
type: string
file_path:
description: Relative path in global-namespace-root form (e.g. "models/checkpoints/flux.safetensors")
nullable: true
type: string
hash:
description: Blake3 hash of the asset content.
pattern: ^blake3:[a-f0-9]{64}$
type: string
id:
description: Asset ID
format: uuid
type: string
job_id:
description: ID of the job that created this asset, if available
format: uuid
nullable: true
type: string
loader_path:
description: The bare value a loader widget consumes for this asset. For models it is the path inside the category folder (e.g. "flux.safetensors" for "models/checkpoints/flux.safetensors"), which is what the model resolver matches. For input/output/temp it is the content hash, because those assets are fetched by hash rather than staged by name — that is the value LoadImage-style widgets must carry. Clients add the "[output]"/"[temp]" annotation from the asset's own type, so it is never included here. Null when no such value can be derived.
nullable: true
type: string
mime_type:
description: Updated MIME type of the asset
type: string
name:
description: Updated name of the asset
type: string
tags:
description: Tags associated with the asset
items:
type: string
type: array
updated_at:
description: Timestamp of the update
format: date-time
type: string
user_metadata:
additionalProperties: true
description: Updated custom metadata
type: object
required:
- id
- updated_at
type: object
ChurnkeyAuthResponse:
description: |
Credentials the Churnkey embed requires to launch the cancel flow.
`auth_hash` is hex-encoded HMAC-SHA256 of `customer_id` signed with the
server's CHURNKEY_HMAC_SECRET; it is bound to that single customer ID
and must not be reused for other customers.
properties:
auth_hash:
description: Hex-encoded HMAC-SHA256(customer_id, CHURNKEY_HMAC_SECRET)
type: string
customer_id:
description: Stripe customer ID for the workspace
type: string
mode:
description: Churnkey environment matching the configured app
enum:
- live
- test
- sandbox
type: string
required:
- customer_id
- auth_hash
- mode
type: object
CreateWorkflowRequest:
description: Request body for creating a new saved workflow.
properties:
default_view:
description: Default view mode
enum:
- workflow
- app
type: string
description:
description: Description of the workflow
type: string
forked_from_workflow_id:
description: ID of the source workflow if forked
type: string
forked_from_workflow_version_id:
description: ID of the source workflow version if forked
type: string
name:
description: Display name for the workflow
type: string
workflow_json:
additionalProperties: true
description: The ComfyUI workflow JSON
type: object
required:
- workflow_json
type: object
CreateWorkflowVersionRequest:
description: Request body for creating a new version of a saved workflow.
properties:
base_version:
description: The version number this change is based on (for optimistic concurrency)
type: integer
workflow_json:
additionalProperties: true
description: The updated ComfyUI workflow JSON
type: object
required:
- base_version
- workflow_json
type: object
ErrorResponse:
description: Standard error response with a machine-readable code and human-readable message.
properties:
code:
type: string
details:
additionalProperties: true
description: Optional open object carrying structured, machine-readable context about the error (e.g. offending field names, validation specifics). Absent for most errors; consumers must not assume any particular shape.
type: object
message:
type: string
required:
- code
- message
type: object
ExecutionError:
description: Detailed execution error information from ComfyUI
properties:
current_inputs:
additionalProperties: true
description: Input values at time of failure (empty object if not available)
type: object
current_outputs:
additionalProperties: true
description: Output values at time of failure (empty object if not available)
type: object
exception_message:
description: Human-readable error message
type: string
exception_type:
description: Python exception type (e.g., "RuntimeError")
type: string
node_id:
description: ID of the node that failed
type: string
node_type:
description: Type name of the node (e.g., "KSampler")
type: string
traceback:
description: Array of traceback lines (empty array if not available)
items:
type: string
type: array
required:
- node_id
- node_type
- exception_message
- exception_type
- traceback
- current_inputs
- current_outputs
type: object
FeedbackRequest:
description: Request to submit user feedback
properties:
content:
description: The feedback content or message
type: string
metadata:
additionalProperties: true
description: Additional metadata about the feedback
type: object
rating:
description: User's rating of ComfyUI Cloud experience (1-5 stars)
maximum: 5
minimum: 1
type: integer
type:
description: Type of feedback being submitted
enum:
- missing_nodes
- general
- missing_models
type: string
required:
- type
type: object
FeedbackResponse:
description: Response after submitting feedback
type: object
ForkWorkflowRequest:
description: Request body for forking an existing workflow into the user's account.
properties:
name:
description: Name for the forked workflow
type: string
source_version:
description: Version number to fork from
type: integer
required:
- source_version
type: object
GetUserDataResponseFull:
description: List of user data file entries (each with path, size, and modification time) returned when full_info=true.
items:
$ref: '#/components/schemas/GetUserDataResponseFullFile'
type: array
GetUserDataResponseFullFile:
description: Individual file entry within a full user data response.
properties:
modified:
description: UNIX timestamp of the last modification in milliseconds.
format: int64
type: integer
path:
description: File name or path relative to the user directory.
type: string
size:
description: File size in bytes.
type: integer
type: object
GlobalSubgraphData:
description: Full data for a global subgraph blueprint
properties:
data:
description: The full subgraph JSON data as a string
type: string
info:
description: Additional information about the subgraph
properties:
node_pack:
description: The node pack/module that provides this subgraph
type: string
required:
- node_pack
type: object
name:
description: Display name of the subgraph blueprint
type: string
source:
description: Source type of the subgraph - "templates" for workflow templates or "custom_node" for custom node subgraphs
type: string
required:
- source
- name
- info
- data
type: object
GlobalSubgraphInfo:
description: Metadata for a global subgraph blueprint (without full data)
properties:
data:
description: The full subgraph JSON data (may be empty in list view)
type: string
info:
description: Additional information about the subgraph
properties:
node_pack:
description: The node pack/module that provides this subgraph
type: string
required:
- node_pack
type: object
name:
description: Display name of the subgraph blueprint
type: string
source:
description: Source type of the subgraph - "templates" for workflow templates or "custom_node" for custom node subgraphs
type: string
required:
- source
- name
- info
type: object
HistoryDetailEntry:
description: History entry with full prompt data
properties:
meta:
additionalProperties: true
description: Metadata about the execution and nodes
type: object
outputs:
additionalProperties: true
description: Output data from execution (generated images, files, etc.)
type: object
prompt:
description: Full prompt execution data
properties:
extra_data:
additionalProperties: true
description: Additional execution data
type: object
outputs_to_execute:
description: Output nodes to execute
items:
type: string
type: array
priority:
description: Execution priority
format: double
type: number
prompt:
additionalProperties: true
description: The workflow nodes
type: object
prompt_id:
description: The prompt ID
type: string
type: object
status:
additionalProperties: true
description: Execution status and timeline information
type: object
type: object
HistoryDetailResponse:
additionalProperties:
$ref: '#/components/schemas/HistoryDetailEntry'
description: |
Detailed execution history response for a specific prompt.
Returns a dictionary with prompt_id as key and full history data as value.
type: object
HistoryEntry:
description: History entry with prompt_id and execution data
properties:
create_time:
description: Job creation timestamp (Unix timestamp in milliseconds)
format: int64
type: integer
meta:
additionalProperties: true
description: Metadata about the execution and nodes
type: object
outputs:
additionalProperties: true
description: Output data from execution (generated images, files, etc.)
type: object
prompt:
description: Filtered prompt execution data (lightweight format)
properties:
extra_data:
additionalProperties: true
description: Additional execution data (workflow removed from extra_pnginfo)
type: object
priority:
description: Execution priority
format: double
type: number
prompt_id:
description: The prompt ID
type: string
type: object
prompt_id:
description: Unique identifier for this prompt execution
type: string
status:
additionalProperties: true
description: Execution status and timeline information
type: object
workflow_id:
description: UUID identifying the workflow graph definition
type: string
required:
- prompt_id
type: object
HistoryManageRequest:
additionalProperties: false
description: Request to manage history operations
properties:
clear:
description: If true, clear all history for the authenticated user
type: boolean
delete:
description: Array of job IDs to delete from history
items:
type: string
type: array
type: object
HistoryResponse:
description: |
Execution history response with history array.
Returns an object with a "history" key containing an array of history entries.
Each entry includes prompt_id as a property along with execution data.
properties:
history:
description: Array of history entries ordered by creation time (newest first)
items:
$ref: '#/components/schemas/HistoryEntry'
type: array
required:
- history
type: object
JobAssetsResponse:
description: Paginated list of the assets produced by a single job.
properties:
assets:
description: The job's output assets for the requested page (empty when the job produced none)
items:
$ref: '#/components/schemas/JobOutputAsset'
type: array
job_id:
description: ID of the job these assets belong to
format: uuid
type: string
pagination:
$ref: '#/components/schemas/PaginationInfo'
required:
- job_id
- assets
- pagination
type: object
JobCancelResponse:
description: Response for POST /api/jobs/{job_id}/cancel. Returned on both fresh cancels and idempotent no-ops.
properties:
cancelled:
description: |
True when a cancel event was successfully dispatched by this call.
False when the job was already in a terminal or cancelling state,
in which case the call is a no-op (still 200 — idempotent).
type: boolean
required:
- cancelled
type: object
JobDetailResponse:
description: Full job details including workflow and outputs
properties:
create_time:
description: Job creation timestamp (Unix timestamp in milliseconds)
format: int64
type: integer
execution_end_time:
description: Workflow execution completion timestamp (Unix milliseconds, only present for terminal states)
format: int64
type: integer
execution_error:
allOf:
- $ref: '#/components/schemas/ExecutionError'
description: Detailed execution error from ComfyUI (only for failed jobs with structured error data)
execution_meta:
additionalProperties: true
description: Node-level execution metadata (only for terminal states)
type: object
execution_start_time:
description: Workflow execution start timestamp (Unix milliseconds, only present once execution has started)
format: int64
type: integer
execution_status:
additionalProperties: true
description: ComfyUI execution status and timeline (only for terminal states)
type: object
id:
description: Unique job identifier
format: uuid
type: string
outputs:
additionalProperties: true
description: Full outputs object from ComfyUI (only for terminal states)
type: object
outputs_count:
description: Total number of output files (omitted for non-terminal states)
type: integer
preview_output:
additionalProperties: true
description: Primary preview output (only for terminal states)
type: object
previewable_outputs_count:
description: Count of outputs classified as previewable media types (images, video, audio, 3D, text) — a subset of outputs_count (omitted for non-terminal states)
type: integer
status:
description: User-friendly job status
enum:
- pending
- in_progress
- completed
- failed
- cancelled
type: string
update_time:
description: Last update timestamp (Unix timestamp in milliseconds)
format: int64
type: integer
user_id:
description: |
ID of the user that owns this job (see the `workspace_id`
description above for why this is always the caller's own id
on a successful response).
type: string
workflow:
additionalProperties: true
description: |
Full ComfyUI workflow (10-100KB, omitted if not available).
Sensitive credentials are redacted before the response is returned:
`extra_data.api_key_comfy_org`, when present, is replaced with the
literal string `"[REDACTED]"`. The field is preserved (not removed)
so existence checks still pass, but the value is not usable.
type: object
workflow_id:
description: UUID identifying the workflow graph definition
type: string
workflow_version_id:
description: |
UUID of the cloud workflow version this job is pinned to, if the
submission carried one (see PromptRequest's workflow_version_id).
Absent for jobs submitted without that association, including
every job submitted through the public API v2 today.
type: string
workspace_id:
description: |
ID of the workspace that owns this job. A successful (200)
response from this operation is only ever returned for the
caller's own job (see this operation's ownership-scoped
query), so this is always the caller's own workspace —
consumers that also need to correlate this job to its
live-progress broadcast channel (workspace+user scoped; see
the internal common/gateways/broadcast package) can use this
value directly rather than resolving their own identity a
second way.
type: string
required:
- id
- status
- create_time
- update_time
type: object
JobEntry:
description: Lightweight job data for list views (workflow and full outputs excluded)
properties:
create_time:
description: Job creation timestamp (Unix timestamp in milliseconds)
format: int64
type: integer
execution_end_time:
description: Workflow execution completion timestamp (Unix milliseconds, only present for terminal states)
format: int64
type: integer
execution_error:
allOf:
- $ref: '#/components/schemas/ExecutionError'
description: Detailed execution error from ComfyUI (only for failed jobs with structured error data)
execution_start_time:
description: Workflow execution start timestamp (Unix milliseconds, only present for terminal states)
format: int64
type: integer
id:
description: Unique job identifier
format: uuid
type: string
outputs_count:
description: Total number of output files (omitted for non-terminal states)
type: integer
preview_output:
additionalProperties: true
description: Primary preview output (only present for terminal states)
type: object
previewable_outputs_count:
description: Count of outputs classified as previewable media types (images, video, audio, 3D, text) — a subset of outputs_count (omitted for non-terminal states)
type: integer
status:
description: User-friendly job status
enum:
- pending
- in_progress
- completed
- failed
- cancelled
type: string
workflow_id:
description: UUID identifying the workflow graph definition
type: string
required:
- id
- status
- create_time
type: object
JobOutputAsset:
description: |
An asset produced by a job, enriched with the per-output node context
(`node_id`, `output_key`, `output_index`) correlated from the job's
execution outputs by content hash. The node-context fields are null
when the asset cannot be matched to an output entry.
properties:
created_at:
description: Timestamp when the asset was created
format: date-time
type: string
hash:
description: Blake3 hash of the asset content.
pattern: ^blake3:[a-f0-9]{64}$
type: string
id:
description: Unique identifier for the asset
format: uuid
type: string
mime_type:
description: MIME type of the asset
type: string
name:
description: Name of the asset file
type: string
node_id:
description: ID of the workflow node that produced this asset, if known
nullable: true
type: string
output_index:
description: Zero-based index of this asset within the node's output slot, if known
nullable: true
type: integer
output_key:
description: Output slot key under the producing node (e.g. "images"), if known
nullable: true
type: string
preview_url:
description: Relative URL for asset preview/thumbnail
format: uri-reference
type: string
size:
description: Size of the asset in bytes
format: int64
type: integer
required:
- id
- name
- created_at
type: object
JobStatusResponse:
description: Job status information
properties:
assigned_inference:
description: The inference instance assigned to this job (if any)
nullable: true
type: string
created_at:
description: When the job was created
format: date-time
type: string
error_message:
description: Error message if the job failed
nullable: true
type: string
id:
description: The job ID
format: uuid
type: string
last_state_update:
description: When the job status was last changed
format: date-time
type: string
status:
description: Current job status
enum:
- waiting_to_dispatch
- pending
- in_progress
- completed
- error
- cancelled
type: string
updated_at:
description: When the job was last updated
format: date-time
type: string
required:
- id
- status
- created_at
- updated_at
type: object
JobsCancelRequest:
additionalProperties: false
description: Request to cancel multiple jobs by ID.
properties:
job_ids:
description: Job identifiers (UUIDs) to cancel.
items:
format: uuid
type: string
maxItems: 100
minItems: 1
type: array
required:
- job_ids
type: object
JobsCancelResponse:
description: Response for POST /api/jobs/cancel.
properties:
cancelled:
description: |
Job IDs for which a cancel event was successfully dispatched by this
call. Jobs already in a terminal or cancelling state are idempotently
skipped and will not appear here.
items:
type: string
type: array
required:
- cancelled
type: object
JobsListResponse:
description: Paginated list of jobs for the authenticated user.
properties:
jobs:
description: Array of jobs ordered by specified sort field
items:
$ref: '#/components/schemas/JobEntry'
type: array
pagination:
$ref: '#/components/schemas/PaginationInfo'
required:
- jobs
- pagination
type: object
ListAssetsResponse:
description: Paginated list of assets belonging to the authenticated user.
properties:
assets:
description: List of assets matching the query
items:
$ref: '#/components/schemas/Asset'
type: array
has_more:
description: Whether more assets are available beyond this page
type: boolean
next_cursor:
description: |
Opaque cursor to pass as the `after` query parameter to fetch the
next page. Omitted from the response when there are no more results.
type: string
total:
description: Total number of assets matching the filters
type: integer
required:
- assets
- total
- has_more
type: object
ListTagsResponse:
description: Paginated list of available asset tags.
properties:
has_more:
description: Whether more tags are available
type: boolean
tags:
description: List of tags
items:
$ref: '#/components/schemas/TagInfo'
type: array
total:
description: Total number of tags
type: integer
required:
- tags
- total
- has_more
type: object
ModelFile:
description: Represents a model file with metadata
properties:
name:
description: The filename of the model
example: model.safetensors
type: string
pathIndex:
description: Index of the path where this model is located
example: 0
type: integer
required:
- name
- pathIndex
type: object
ModelFolder:
description: Represents a folder containing models
properties:
folders:
description: List of paths where models of this type are stored
example:
- checkpoints
items:
type: string
type: array
name:
description: The name of the model folder
example: checkpoints
type: string
required:
- name
- folders
type: object
NodeInfo:
description: Metadata describing a single ComfyUI node type and its inputs/outputs.
properties:
api_node:
description: Whether this is an API node
type: boolean
category:
description: Category of the node
type: string
deprecated:
description: Whether the node is deprecated
type: boolean
description:
description: Description of the node
type: string
display_name:
description: Display name of the node
type: string
experimental:
description: Whether the node is experimental
type: boolean
input:
additionalProperties: true
description: Input specifications for the node
type: object
input_order:
additionalProperties:
items:
type: string
type: array
description: Order of inputs for display
type: object
name:
description: Internal name of the node
type: string
output:
description: Output types of the node
items:
type: string
type: array
output_is_list:
description: Whether each output is a list
items:
type: boolean
type: array
output_name:
description: Names of the outputs
items:
type: string
type: array
output_node:
description: Whether this is an output node
type: boolean
output_tooltips:
description: Tooltips for outputs
items:
type: string
type: array
python_module:
description: Python module implementing the node
type: string
type: object
PaginationInfo:
description: |
Pagination metadata included in list responses. Supports both legacy
offset/limit pagination and cursor-based pagination. When cursor-based
pagination is used, `next_cursor` is the primary pagination token and
`offset`/`total` may be zero.
properties:
has_more:
description: Whether more items are available beyond this page
type: boolean
limit:
description: Items per page
minimum: 1
type: integer
next_cursor:
description: |
Opaque cursor for the next page. Pass this value as the `after`
query parameter on the next request. Empty or absent when there
are no more results.
type: string
offset:
deprecated: true
description: 'Current offset (0-based). Deprecated: use cursor-based pagination.'
minimum: 0
type: integer
total:
description: Total number of items matching filters (may be 0 when using cursor pagination)
minimum: 0
type: integer
required:
- offset
- limit
- total
- has_more
type: object
PromptErrorResponse:
additionalProperties: true
description: Error response for ComfyUI prompt execution.
type: object
PromptInfo:
description: Metadata about the currently running and queued prompts.
properties:
exec_info:
properties:
queue_remaining:
description: Number of items remaining in the queue
type: integer
type: object
type: object
PromptRequest:
description: Request body for submitting a ComfyUI workflow prompt for execution.
properties:
extra_data:
additionalProperties: true
description: Extra data to be associated with the prompt
type: object
front:
description: If true, adds the prompt to the front of the queue
type: boolean
number:
description: Priority number for the queue (lower numbers have higher priority)
type: number
partial_execution_targets:
description: List of node names to execute
items:
type: string
type: array
prompt:
additionalProperties: true
description: The workflow graph to execute
type: object
workflow_id:
description: UUID identifying the cloud workflow entity to associate with this job
type: string
workflow_version_id:
description: UUID identifying the workflow version to associate with this job
type: string
required:
- prompt
type: object
PromptResponse:
description: Response returned after successfully queuing a workflow prompt.
properties:
node_errors:
additionalProperties: true
description: Any errors in the nodes of the prompt
type: object
number:
description: Priority number in the queue
type: number
prompt_id:
description: Unique identifier for the prompt execution
format: uuid
type: string
type: object
PublishWorkflowAssetsRequest:
description: Request body for publishing workflow assets to the Hub.
properties:
asset_ids:
description: IDs of assets (inputs and models) to snapshot.
items:
type: string
type: array
required:
- asset_ids
type: object
PublishedWorkflowDetail:
description: Full detail of a publicly published workflow on the Hub.
properties:
assets:
description: Published assets with their library status for the caller.
items:
$ref: '#/components/schemas/AssetInfo'
type: array
listed:
type: boolean
name:
description: Human-readable workflow name.
type: string
publish_time:
format: date-time
nullable: true
type: string
share_id:
type: string
workflow_id:
type: string
workflow_json:
additionalProperties: true
description: The workflow JSON content at publish time.
type: object
required:
- share_id
- workflow_id
- name
- listed
- workflow_json
- assets
type: object
QueueInfo:
description: Queue information with pending and running jobs
properties:
queue_pending:
description: Array of pending job items (ordered by creation time, oldest first)
items:
description: |
Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata]
- [0] job_number (integer): Position in queue (1-based)
- [1] prompt_id (string): Job UUID
- [2] workflow_json (object): Full ComfyUI workflow
- [3] output_node_ids (array): Node IDs to return results from
- [4] metadata (object): Contains {create_time: <milliseconds>}
items: {}
maxItems: 5
minItems: 5
type: array
type: array
queue_running:
description: Array of currently running job items
items:
description: |
Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata]
- [0] job_number (integer): Position in queue (1-based)
- [1] prompt_id (string): Job UUID
- [2] workflow_json (object): Full ComfyUI workflow
- [3] output_node_ids (array): Node IDs to return results from
- [4] metadata (object): Contains {create_time: <milliseconds>}
items: {}
maxItems: 5
minItems: 5
type: array
type: array
type: object
QueueManageRequest:
additionalProperties: false
description: Request to manage queue operations
properties:
clear:
description: If true, clear all pending jobs from the queue
type: boolean
delete:
description: Array of job IDs to cancel; pending and running jobs transition to cancelled
items:
type: string
type: array
type: object
QueueManageResponse:
description: Response after a queue management action (delete or clear).
properties:
cleared:
description: Whether the queue was cleared
type: boolean
deleted:
description: Array of job IDs that were successfully cancelled
items:
type: string
type: array
type: object
SystemStatsResponse:
description: System statistics response
properties:
devices:
items:
properties:
name:
description: Device name
type: string
type:
description: Device type
type: string
vram_free:
description: Free VRAM in bytes
type: number
vram_total:
description: Total VRAM in bytes
type: number
required:
- name
- type
type: object
type: array
system:
properties:
argv:
description: Command line arguments
items:
type: string
type: array
cloud_version:
description: Cloud ingest service version (commit hash)
type: string
comfyui_frontend_version:
description: ComfyUI frontend version (commit hash or tag)
type: string
comfyui_version:
description: ComfyUI version
type: string
deploy_environment:
description: How this ComfyUI instance is deployed (e.g. cloud, local-git, local-portable, local-desktop)
type: string
embedded_python:
description: Whether using embedded Python
type: boolean
os:
description: Operating system
type: string
python_version:
description: Python version
type: string
pytorch_version:
description: PyTorch version
type: string
ram_free:
description: Free RAM in bytes
type: number
ram_total:
description: Total RAM in bytes
type: number
workflow_templates_version:
description: Workflow templates version
type: string
required:
- os
- python_version
- embedded_python
- comfyui_version
- pytorch_version
- argv
- ram_total
- ram_free
type: object
required:
- system
- devices
type: object
TagInfo:
description: Metadata for a single tag that can be applied to assets.
properties:
count:
description: Number of assets using this tag
type: integer
name:
description: Tag name
type: string
required:
- name
- count
type: object
TagsModificationResponse:
description: Response after adding, updating, or removing tags on an asset.
properties:
added:
description: Tags that were successfully added (for add operation)
items:
type: string
type: array
already_present:
description: Tags that were already present (for add operation)
items:
type: string
type: array
not_present:
description: Tags that were not present (for remove operation)
items:
type: string
type: array
removed:
description: Tags that were successfully removed (for remove operation)
items:
type: string
type: array
total_tags:
description: All tags on the asset after the operation
items:
type: string
type: array
required:
- total_tags
type: object
TaskEntry:
description: Task data for list views
properties:
completed_at:
description: When task completed or failed (null if not finished)
format: date-time
type: string
create_time:
description: Task creation timestamp
format: date-time
type: string
id:
description: Unique task identifier
format: uuid
type: string
started_at:
description: When task execution started (null if not started)
format: date-time
type: string
status:
description: Current task status
enum:
- created
- running
- completed
- failed
type: string
task_name:
description: Task type name (e.g., model_upload)
type: string
required:
- id
- task_name
- status
- create_time
type: object
TaskResponse:
description: Full task details including payload and result
properties:
completed_at:
description: When task completed or failed (null if not finished)
format: date-time
type: string
create_time:
description: Task creation timestamp
format: date-time
type: string
error_message:
description: Error message on failure (null if not failed)
type: string
id:
description: Unique task identifier
format: uuid
type: string
idempotency_key:
description: Caller-provided key for idempotent task creation
type: string
payload:
additionalProperties: true
description: Task input data
type: object
result:
additionalProperties: true
description: Task output data (null if not completed)
type: object
started_at:
description: When task execution started (null if not started)
format: date-time
type: string
status:
description: Current task status
enum:
- created
- running
- completed
- failed
type: string
task_name:
description: Task type name (e.g., model_upload)
type: string
update_time:
description: Task last update timestamp
format: date-time
type: string
required:
- id
- idempotency_key
- task_name
- payload
- status
- create_time
- update_time
type: object
TasksListResponse:
description: Paginated list of background tasks for the authenticated user.
properties:
pagination:
$ref: '#/components/schemas/PaginationInfo'
tasks:
description: Array of tasks ordered by create_time
items:
$ref: '#/components/schemas/TaskEntry'
type: array
required:
- tasks
- pagination
type: object
UpdateWorkflowRequest:
description: Request body for updating an existing saved workflow.
properties:
default_view:
description: New default view mode
enum:
- workflow
- app
type: string
description:
description: New description
type: string
name:
description: New display name
type: string
type: object
UserDataResponseFull:
description: User data listing entry with file metadata (path, size, modification time).
properties:
modified:
description: UNIX timestamp of the last modification in milliseconds.
format: int64
type: integer
path:
type: string
size:
type: integer
type: object
UserResponse:
description: User information response
properties:
id:
description: Firebase UID of the authenticated user
type: string
status:
description: User status (always "active" for authenticated users)
type: string
required:
- id
- status
type: object
WorkflowForkedFrom:
description: Reference to the parent workflow from which this workflow was forked.
properties:
workflow_id:
type: string
workflow_version_id:
type: string
type: object
WorkflowListResponse:
description: Paginated list of saved workflows.
properties:
data:
items:
$ref: '#/components/schemas/WorkflowResponse'
type: array
pagination:
$ref: '#/components/schemas/PaginationInfo'
required:
- data
- pagination
type: object
WorkflowPublishInfo:
description: Publishing metadata for a workflow shared to the Hub.
properties:
assets:
description: Published assets (inputs and models).
items:
$ref: '#/components/schemas/AssetInfo'
type: array
listed:
type: boolean
publish_time:
format: date-time
nullable: true
type: string
share_id:
type: string
workflow_id:
type: string
required:
- workflow_id
- share_id
- listed
- assets
type: object
WorkflowResponse:
description: Full workflow entity including metadata and version history.
properties:
created_at:
format: date-time
type: string
created_by:
type: string
default_view:
enum:
- workflow
- app
type: string
description:
type: string
forked_from:
$ref: '#/components/schemas/WorkflowForkedFrom'
id:
type: string
latest_version:
type: integer
name:
type: string
updated_at:
format: date-time
type: string
required:
- id
- latest_version
- created_by
- created_at
- updated_at
type: object
WorkflowVersionContentResponse:
description: Full workflow version including the serialized workflow JSON.
properties:
created_at:
format: date-time
type: string
created_by:
type: string
dependency_asset_ids:
items:
type: string
type: array
id:
type: string
version:
type: integer
workflow_json:
additionalProperties: true
type: object
required:
- id
- version
- workflow_json
- created_by
- created_at
type: object
WorkflowVersionResponse:
description: Metadata for a single workflow version.
properties:
created_at:
format: date-time
type: string
created_by:
type: string
id:
type: string
latest_version:
type: integer
version:
type: integer
required:
- id
- version
- latest_version
- created_by
- created_at
type: object
securitySchemes:
ApiKeyAuth:
description: |
API key authentication. Keys are prefixed with 'comfyui-' and can be
generated from user account settings. Example: 'comfyui-abc123...'
in: header
name: X-API-Key
type: apiKey
BearerAuth:
bearerFormat: JWT
description: |
Firebase JWT token authentication. Obtain a token by authenticating
with Firebase and pass it in the Authorization header.
scheme: bearer
type: http
CookieAuth:
description: |
Session cookie authentication. Set automatically after successful
login via the /api/auth/session endpoint.
in: cookie
name: session
type: apiKey
info:
description: |
API for ComfyUI - A powerful and modular UI for Stable Diffusion.
This API allows you to interact with ComfyUI programmatically, including:
- Retrieving prompt information
- Retrieving node information
license:
name: GNU General Public License v3.0
url: https://github.com/Comfy-Org/ComfyUI/blob/master/LICENSE
title: ComfyUI API
version: 1.0.0
openapi: 3.0.3
paths:
/api/assets:
get:
description: |
Retrieves a paginated list of assets belonging to the authenticated user.
Supports filtering by tags, name, metadata, and sorting options.
operationId: listAssets
parameters:
- deprecated: true
description: |
Deprecated alias for `tags_all`, kept permanently for existing
callers. Filter assets that have ALL of these tags. Combining it
with `tags_all`, or exceeding 100 tags (counted after removing
empty values and duplicates), returns 400 `INVALID_TAG_FILTER`.
explode: false
in: query
name: include_tags
schema:
items:
type: string
type: array
style: form
- deprecated: true
description: |
Deprecated alias for `tags_none`, kept permanently for existing
callers. Exclude assets that have ANY of these tags. Combining it
with `tags_none`, or exceeding 100 tags (counted after removing
empty values and duplicates), returns 400 `INVALID_TAG_FILTER`.
explode: false
in: query
name: exclude_tags
schema:
items:
type: string
type: array
style: form
- description: |
Filter assets that have ALL of these tags. Tag values are opaque
byte-strings compared exactly and case-sensitively; unknown tags
are not an error — they simply match nothing. Replaces the
deprecated `include_tags`. Sending both spellings, listing the
same tag here and in `tags_none`, or exceeding 100 tags per list
(counted after removing empty values and duplicates) returns 400
`INVALID_TAG_FILTER`.
explode: false
in: query
name: tags_all
schema:
items:
type: string
type: array
style: form
- description: |
Filter assets that have AT LEAST ONE of these tags. Combines with
`tags_all`/`tags_none` by intersection (`tags_none` always wins;
overlap with `tags_none` is allowed and leaves a dead term).
Supplying a positive tag filter (`tags_any`, `tags_all`, or
`include_tags`) replaces the default category filter that is
otherwise applied. Lists over 100 tags (counted after removing
empty values and duplicates) return 400 `INVALID_TAG_FILTER`.
explode: false
in: query
name: tags_any
schema:
items:
type: string
type: array
style: form
- description: |
Exclude assets that have ANY of these tags. Replaces the
deprecated `exclude_tags`. Sending both spellings, or exceeding
100 tags per list (counted after removing empty values and
duplicates), returns 400 `INVALID_TAG_FILTER`.
explode: false
in: query
name: tags_none
schema:
items:
type: string
type: array
style: form
- description: Filter assets where name contains this substring (case-insensitive)
in: query
name: name_contains
schema:
type: string
- description: JSON object for filtering by metadata fields
in: query
name: metadata_filter
schema:
type: string
- description: Maximum number of assets to return (1-500)
in: query
name: limit
schema:
default: 20
maximum: 500
minimum: 1
type: integer
- description: Number of assets to skip for pagination
in: query
name: offset
schema:
default: 0
minimum: 0
type: integer
- description: Field to sort by
in: query
name: sort
schema:
default: created_at
enum:
- name
- created_at
- updated_at
- size
- last_access_time
type: string
- description: Sort order
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: Whether to include public/shared assets in results
in: query
name: include_public
schema:
default: true
type: boolean
- description: |
Filter assets by content hash, in the canonical `blake3:<hex>`
form. Matches regardless of which of this asset store's two
internal hash storage formats the matching row was written
under (the canonical form used by from-hash-created references,
or the raw `<hex>.<ext>`/bare `<hex>` storage key used by direct
uploads) — both represent the same content hash.
in: query
name: hash
schema:
type: string
- description: |
Opaque cursor for keyset pagination. Pass the `next_cursor` value
from the previous response to fetch the next page. When provided,
`offset` is ignored. Cursor pagination is only supported with
`sort` values `created_at`, `updated_at`, `name`, or `size`;
requests combining `after` with other sort fields return 400.
The cursor must have been minted under the same `sort` value used
in the follow-up request.
in: query
name: after
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ListAssetsResponse'
description: Success - Assets returned
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request parameters
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: List user assets
tags:
- file
post:
description: |
Creates a new asset from a direct file upload (multipart/form-data) with associated metadata.
If an asset with the same hash already exists, returns the existing asset.
operationId: createAsset
requestBody:
content:
multipart/form-data:
schema:
properties:
file:
description: The asset file to upload
format: binary
type: string
hash:
description: Content hash of the file.
pattern: ^(blake3|sha256):[a-f0-9]{64}$
type: string
id:
description: Optional asset ID for idempotent creation. If provided and asset exists, returns existing asset.
format: uuid
type: string
mime_type:
description: MIME type of the asset (e.g., "image/png", "video/mp4")
type: string
name:
description: Display name for the asset
type: string
preview_id:
description: Optional preview asset ID. If not provided, images will use their own ID as preview.
format: uuid
type: string
tags:
description: JSON-encoded array of freeform tag strings, e.g. '["models","checkpoint"]'. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.
type: string
user_metadata:
description: Custom JSON metadata as a string
type: string
required:
- file
type: object
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/AssetCreated'
description: |
Asset already existed for this user (deduplicated by content hash); the
existing asset is returned with created_new=false.
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/AssetCreated'
description: Asset created successfully (created_new=true)
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request (bad file, invalid content type, etc.)
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"413":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: File too large
"415":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unsupported media type
"422":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error (e.g., disallowed model_type tag)
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Create a new asset
tags:
- file
/api/assets/{id}:
delete:
description: Deletes the asset record.
operationId: deleteAsset
parameters:
- description: Asset ID
in: path
name: id
required: true
schema:
format: uuid
type: string
responses:
"204":
description: Asset record deleted successfully
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Asset not found
"409":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: 'Asset cannot be deleted because it is referenced by another resource, e.g. a workflow version (error code: ASSET_IN_USE)'
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Delete asset
tags:
- file
get:
description: Retrieves detailed information about a specific asset
operationId: getAssetById
parameters:
- description: Asset ID
in: path
name: id
required: true
schema:
format: uuid
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/Asset'
description: Asset details retrieved successfully
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Asset not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get asset details
tags:
- file
put:
description: |
Updates an asset's metadata. At least one field must be provided.
Only name, mime_type, preview_id, and user_metadata can be updated.
For tag management, use POST (add) and DELETE (remove) /api/assets/{id}/tags.
operationId: updateAsset
parameters:
- description: Asset ID
in: path
name: id
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/json:
schema:
minProperties: 1
properties:
mime_type:
description: Updated MIME type of the asset
type: string
name:
description: New display name for the asset
type: string
preview_id:
description: Updated preview asset ID
format: uuid
type: string
user_metadata:
additionalProperties: true
description: Updated custom metadata
type: object
type: object
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/AssetUpdated'
description: Asset updated successfully
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: |
Invalid request — no fields provided, or `preview_id` is the zero UUID
(`INVALID_PREVIEW_ID`).
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: |
Asset not found — returned both when the asset being updated does
not exist and when `preview_id` does not reference an asset
accessible to the caller.
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Update asset metadata
tags:
- file
/api/assets/{id}/content:
get:
description: |
Returns the binary content of an asset by ID.
The contract is the same across runtimes — "GET this path and you
receive the asset's bytes" — but the mechanism differs:
- **Local ComfyUI** streams the bytes directly (`200`,
`application/octet-stream`).
- **Cloud** does not proxy large files; it responds `302` with a
`Location` redirect to a short-lived signed storage URL. Clients that
follow redirects (browsers, `fetch`/XHR, `<img>`/`<video>`) receive
the bytes transparently.
Prefer this over the filename-addressed `/api/view` when you have an
asset ID.
operationId: getAssetContent
parameters:
- description: Asset ID
in: path
name: id
required: true
schema:
type: string
- description: |
Content-Disposition for the response: `attachment` (download) or
`inline` (render in browser). Defaults to `attachment`.
in: query
name: disposition
schema:
default: attachment
enum:
- inline
- attachment
type: string
responses:
"200":
content:
application/octet-stream:
schema:
format: binary
type: string
description: Asset content stream (local runtime streams the bytes directly)
"302":
description: Redirect to a signed storage URL (cloud runtime)
headers:
Cache-Control:
description: Private caching directive scoped to the signed URL lifetime
schema:
type: string
Location:
description: Short-lived signed URL to the asset content in storage
schema:
type: string
Vary:
description: Partitions any cached redirect by auth credentials so a private redirect is not reused across users
schema:
type: string
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Asset not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
security:
- ApiKeyAuth: []
- BearerAuth: []
- CookieAuth: []
summary: Get asset content
tags:
- file
/api/assets/{id}/tags:
delete:
description: Removes one or more tags from an existing asset
operationId: removeAssetTags
parameters:
- description: Asset ID
in: path
name: id
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/json:
schema:
properties:
tags:
description: Tags to remove from the asset
items:
type: string
minItems: 1
type: array
required:
- tags
type: object
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/TagsModificationResponse'
description: Tags removed successfully
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Asset not found
"422":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error (e.g., reserved tag)
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Remove tags from asset
tags:
- file
post:
description: Adds one or more tags to an existing asset
operationId: addAssetTags
parameters:
- description: Asset ID
in: path
name: id
required: true
schema:
format: uuid
type: string
requestBody:
content:
application/json:
schema:
properties:
tags:
description: Tags to add to the asset
items:
type: string
minItems: 1
type: array
required:
- tags
type: object
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/TagsModificationResponse'
description: Tags added successfully
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Asset not found
"422":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error (e.g., reserved tag)
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Add tags to asset
tags:
- file
/api/assets/from-hash:
post:
description: |
Creates a new asset reference using an existing asset's hash.
This avoids re-uploading the file content when the asset already exists in storage.
The user can provide their own metadata and tags for the reference.
operationId: createAssetFromHash
requestBody:
content:
application/json:
schema:
properties:
hash:
description: 'Blake3 content hash of the existing asset (blake3: prefix)'
pattern: ^blake3:[a-f0-9]{64}$
type: string
mime_type:
description: MIME type of the asset (e.g., "image/png", "video/mp4")
type: string
name:
description: Display name for the asset reference (optional)
type: string
tags:
description: Freeform tags for the asset. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.
items:
type: string
minItems: 1
type: array
user_metadata:
additionalProperties: true
description: Custom metadata for this asset reference
type: object
required:
- hash
- tags
type: object
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/AssetCreated'
description: |
Asset reference already existed for this user (deduplicated by content
hash); the existing asset is returned with created_new=false.
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/AssetCreated'
description: Asset reference created successfully (created_new=true)
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request (bad hash format, invalid tags, etc.)
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Source asset with given hash not found
"422":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error (e.g., disallowed model_type tag)
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Create asset reference from existing hash
tags:
- file
/api/assets/hash/{hash}:
head:
description: |
Checks if an asset exists in the system by its blake3 hash.
Returns 200 if the asset exists, 404 if it doesn't.
operationId: checkAssetByHash
parameters:
- description: Blake3 hash of the asset in format 'blake3:hex_digest'
in: path
name: hash
required: true
schema:
example: blake3:a1b2c3d4e5f67890123456789012345678901234567890123456789012345678
pattern: ^blake3:[a-f0-9]{64}$
type: string
responses:
"200":
description: Asset exists
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid hash format
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
description: Asset not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Check if asset exists by hash
tags:
- file
/api/assets/prune:
post:
description: Starts a background job that removes asset entries whose underlying content no longer exists on disk.
operationId: pruneAssets
responses:
"200":
content:
application/json:
schema:
properties:
marked:
description: Number of assets marked as missing
type: integer
status:
type: string
type: object
description: Prune result
summary: Mark assets whose backing files no longer exist on disk
/api/assets/seed:
post:
description: Starts a background job that scans configured directories and registers assets not yet in the asset database.
operationId: seedAssets
requestBody:
content:
application/json:
schema:
properties:
roots:
description: Root folder paths to scan (if omitted, scans all)
items:
type: string
type: array
type: object
responses:
"200":
content:
application/json:
schema:
properties:
status:
type: string
type: object
description: Seed started
summary: Trigger asset scan/seed from filesystem
/api/assets/seed/cancel:
post:
description: Requests cancellation of the currently-running asset seed job.
operationId: cancelAssetSeed
responses:
"200":
content:
application/json:
schema:
properties:
status:
type: string
type: object
description: Scan cancelled
summary: Cancel an in-progress asset scan
/api/assets/seed/status:
get:
description: Returns progress/status of the most recent asset seed job.
operationId: getAssetSeedStatus
responses:
"200":
content:
application/json:
schema:
additionalProperties: true
description: Scan progress details (files scanned, total, status, etc.)
type: object
description: Scan progress
summary: Get asset scan progress
/api/assets/tags/refine:
get:
description: |
Returns a histogram of tags appearing on assets matching the given filters.
Useful for refining asset searches by showing available tags and their counts.
Only returns tags with non-zero counts (tags that exist on matching assets).
operationId: getAssetTagHistogram
parameters:
- deprecated: true
description: |
Deprecated alias for `tags_all`, kept permanently for existing
callers. Filter assets that have ALL of these tags. The same
combination and list-size rules as on `/api/assets` apply
(400 `INVALID_TAG_FILTER`).
explode: false
in: query
name: include_tags
schema:
items:
type: string
type: array
style: form
- deprecated: true
description: |
Deprecated alias for `tags_none`, kept permanently for existing
callers. Exclude assets that have ANY of these tags. The same
combination and list-size rules as on `/api/assets` apply
(400 `INVALID_TAG_FILTER`).
explode: false
in: query
name: exclude_tags
schema:
items:
type: string
type: array
style: form
- description: |
Filter assets that have ALL of these tags. Replaces the deprecated
`include_tags`. The same combination and list-size rules as on
`/api/assets` apply (400 `INVALID_TAG_FILTER`).
explode: false
in: query
name: tags_all
schema:
items:
type: string
type: array
style: form
- description: |
Filter assets that have AT LEAST ONE of these tags. Combines with
`tags_all`/`tags_none` by intersection (`tags_none` always wins).
The same combination and list-size rules as on `/api/assets` apply
(400 `INVALID_TAG_FILTER`).
explode: false
in: query
name: tags_any
schema:
items:
type: string
type: array
style: form
- description: |
Exclude assets that have ANY of these tags. Replaces the deprecated
`exclude_tags`. The same combination and list-size rules as on
`/api/assets` apply (400 `INVALID_TAG_FILTER`).
explode: false
in: query
name: tags_none
schema:
items:
type: string
type: array
style: form
- description: Filter assets where name contains this substring (case-insensitive)
in: query
name: name_contains
schema:
type: string
- description: JSON object for filtering by metadata fields
in: query
name: metadata_filter
schema:
type: string
- description: Maximum number of tags to return (1-1000, default 100)
in: query
name: limit
schema:
default: 100
maximum: 1000
minimum: 1
type: integer
- description: Whether to include public/shared assets in results
in: query
name: include_public
schema:
default: true
type: boolean
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/AssetTagHistogramResponse'
description: Success - Tag histogram returned
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request parameters
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get tag histogram for filtered assets
tags:
- file
/api/billing/churnkey/auth:
get:
description: |
Returns the Stripe customer identifier and a server-signed
HMAC-SHA256 of the customer ID, used to launch the Churnkey-hosted
cancellation flow embed.
operationId: getChurnkeyAuth
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ChurnkeyAuthResponse'
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Workspace has no Stripe customer (never subscribed)
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
"503":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Churnkey is not configured on the server
security:
- BearerAuth: []
summary: Get Churnkey HMAC auth credentials
tags:
- billing
/api/embeddings:
get:
description: Returns the list of text-encoder embeddings available on disk.
operationId: getEmbeddings
responses:
"200":
content:
application/json:
schema:
items:
type: string
type: array
description: Embedding names
summary: List available embedding names
/api/experiment/models:
get:
description: |
Returns a list of model folders available in the system.
This is an experimental endpoint that replaces the legacy /models endpoint.
Each folder's name is the identifier to pass to /api/experiment/models/{folder}.
The folder vocabulary is resolved per request from the caller's identity: where the
model_type migration is active for that caller the names are model_type folder_names
(e.g. `ultralytics_bbox`), and a folder with no folder_name mapping is returned by its
directory path. An authenticated response can therefore differ from an anonymous one.
operationId: getModelFolders
responses:
"200":
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ModelFolder'
type: array
description: Success - List of model folders
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
security:
- ApiKeyAuth: []
- BearerAuth: []
- {}
summary: Get available model folders
tags:
- file
/api/experiment/models/{folder}:
get:
description: |
Returns a list of models available in the specified folder.
This is an experimental endpoint that provides enhanced model information.
Accepted folder identifiers are those returned by /api/experiment/models for the same
caller. That vocabulary is request-scoped, so list folders and fetch a folder's models
with the same credentials — a name obtained anonymously may not resolve when
authenticated, and vice versa.
operationId: getModelsInFolder
parameters:
- description: The folder name to list models from
in: path
name: folder
required: true
schema:
example: checkpoints
type: string
responses:
"200":
content:
application/json:
schema:
items:
$ref: '#/components/schemas/ModelFile'
type: array
description: Success - List of models in the folder
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Folder not found or no models in folder
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
security:
- ApiKeyAuth: []
- BearerAuth: []
- {}
summary: Get models in a specific folder
tags:
- file
/api/extensions:
get:
description: |
Returns the list of custom node web extension JS files available for
loading by the ComfyUI frontend. Paths are relative to the web root
(e.g. `/extensions/VHS.core.js`).
operationId: getExtensions
responses:
"200":
content:
application/json:
schema:
description: URL paths (relative to web root) of available extension JS files
items:
type: string
type: array
description: JSON array of extension file paths
security: []
summary: List custom node JS extensions
tags:
- node
/api/features:
get:
description: Returns the server's feature capabilities
operationId: getFeatures
responses:
"200":
content:
application/json:
schema:
additionalProperties: true
properties:
free_tier_balance:
description: Free-tier job allowance for an authenticated non-paid (FREE-tier) user in the rollout. Absent for paid users and unauthenticated requests. Synthesized from config before a grant row exists so a brand-new user still sees their full allowance.
properties:
allowance:
description: Total free jobs granted for the current period
type: integer
remaining:
description: Free jobs remaining (allowance - used, floored at 0)
type: integer
used:
description: Free jobs consumed so far
type: integer
required:
- allowance
- used
- remaining
type: object
max_upload_size:
description: Maximum upload size in bytes
type: integer
supports_preview_metadata:
description: Whether the server supports preview metadata
type: boolean
type: object
description: Success
headers:
Cache-Control:
description: Short-lived private cache to deduplicate rapid-fire calls from the frontend
schema:
type: string
Vary:
description: Cache key includes auth headers so anonymous and authenticated responses are stored separately
schema:
type: string
security:
- ApiKeyAuth: []
- BearerAuth: []
- CookieAuth: []
- {}
summary: Get server feature flags
tags:
- node
/api/feedback:
post:
description: Submit feedback about the ComfyUI service
operationId: submitFeedback
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/FeedbackRequest'
required: true
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/FeedbackResponse'
description: Feedback submitted successfully
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Submit user feedback
tags:
- feedback
/api/files/mask-layers:
get:
description: |
Given a mask file (any of the 4 layers), returns all related mask layer files.
This is used by the mask editor to load the paint, mask, and painted layers
when reopening a previously edited mask.
operationId: getMaskLayers
parameters:
- description: Hash filename of any mask layer file
in: query
name: filename
required: true
schema:
example: abc123def456.png
type: string
responses:
"200":
content:
application/json:
schema:
properties:
mask:
description: Filename of the mask layer
nullable: true
type: string
paint:
description: Filename of the paint strokes layer
nullable: true
type: string
painted:
description: Filename of the painted image layer
nullable: true
type: string
painted_masked:
description: Filename of the final composite layer
nullable: true
type: string
type: object
description: Success - Related mask layers returned
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: File not found or not a mask file
summary: Get related mask layer files
tags:
- file
/api/free:
post:
description: Frees GPU memory by unloading models and/or freeing the resident model cache.
operationId: freeMemory
requestBody:
content:
application/json:
schema:
properties:
free_memory:
description: Run garbage collection and free cached memory
type: boolean
unload_models:
description: Unload all models from VRAM/RAM
type: boolean
type: object
responses:
"200":
description: Memory freed
summary: Free GPU memory and/or unload models
/api/global_subgraphs:
get:
description: |
Returns a list of globally available subgraph blueprints.
These are pre-built workflow components that can be used as nodes.
The data field contains a promise that resolves to the full subgraph JSON.
operationId: getGlobalSubgraphs
responses:
"200":
content:
application/json:
schema:
additionalProperties:
$ref: '#/components/schemas/GlobalSubgraphInfo'
type: object
description: Success - Map of subgraph IDs to their metadata
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
security: []
summary: Get available subgraph blueprints
tags:
- workflow
/api/global_subgraphs/{id}:
get:
description: Returns the full data for a specific subgraph blueprint by ID
operationId: getGlobalSubgraph
parameters:
- description: The unique identifier of the subgraph blueprint
in: path
name: id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GlobalSubgraphData'
description: Success - Full subgraph data
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Subgraph not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
security: []
summary: Get a specific subgraph blueprint
tags:
- workflow
/api/history:
post:
deprecated: true
description: |
**Deprecated.** Superseded by the job-management endpoints under
`/api/jobs`. Planned for removal no earlier than a future major
release; sunset timeline TBD.
Clear all history for the authenticated user or delete specific job IDs.
Supports clearing all history or deleting specific job IDs.
operationId: manageHistory
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/HistoryManageRequest'
required: true
responses:
"200":
description: Success - History management operation completed
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request parameters
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Manage execution history
tags:
- workflow
/api/history_v2:
get:
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.
Retrieve execution history for the authenticated user with pagination support.
Returns a lightweight history format with filtered prompt data (workflow removed from extra_pnginfo).
operationId: getHistory
parameters:
- description: Maximum number of items to return
in: query
name: max_items
schema:
type: integer
- description: Starting position (default 0)
in: query
name: offset
schema:
default: 0
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/HistoryResponse'
description: Success - Execution history retrieved
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get execution history (v2)
tags:
- workflow
/api/history_v2/{prompt_id}:
get:
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.
Retrieve detailed execution history for a specific prompt ID.
Returns full history data including complete prompt information.
operationId: getHistoryForPrompt
parameters:
- description: The prompt ID to retrieve history for
in: path
name: prompt_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/HistoryDetailResponse'
description: Success - History for prompt retrieved
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Prompt not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get history for specific prompt
tags:
- workflow
/api/i18n:
get:
description: Returns translation file URLs contributed by custom nodes, keyed by locale.
operationId: getI18n
responses:
"200":
content:
application/json:
schema:
additionalProperties: true
description: Nested map of locale to translation key-value pairs
type: object
description: Translation map
summary: Get internationalisation translation strings
/api/interrupt:
post:
deprecated: true
description: |
Deprecated. Prefer the jobs-namespace cancel endpoints:
POST /api/jobs/{job_id}/cancel for a single job, or
POST /api/jobs/cancel to cancel jobs by ID.
Cancels the first active job for the authenticated user (the currently
running job if there is one, otherwise the next pending job). Takes no
body and cannot target a specific job — use the jobs-namespace endpoints
for that.
operationId: interruptJob
responses:
"200":
description: Success - first active job cancelled, or no active job found
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Interrupt the first active job
tags:
- queue
/api/job/{job_id}/status:
get:
deprecated: true
description: |
**Deprecated.** Superseded by `GET /api/jobs/{job_id}` (plural path).
Clients should migrate; the endpoint is retained for backward
compatibility but will be removed in a future release.
operationId: getJobStatus
parameters:
- description: The unique ID of the job
in: path
name: job_id
required: true
schema:
format: uuid
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/JobStatusResponse'
description: Success - Job status returned
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Forbidden - job belongs to another user
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Job not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get job status (deprecated)
tags:
- job
/api/jobs:
get:
description: |
Retrieve a paginated list of jobs for the authenticated user.
Returns lightweight job data optimized for list views.
Workflow and full outputs are excluded to reduce payload size.
operationId: listJobs
parameters:
- description: Filter by one or more statuses (comma-separated). If not provided, returns all jobs.
example: pending,in_progress
in: query
name: status
schema:
type: string
- description: Filter by workflow ID (exact match)
example: 550e8400-e29b-41d4-a716-446655440000
in: query
name: workflow_id
schema:
type: string
- description: Filter by output media type (only applies to completed jobs with outputs)
example: image
in: query
name: output_type
schema:
enum:
- image
- video
- audio
- 3d
type: string
- description: Field to sort by (create_time = when job was submitted, execution_time = how long workflow took to run)
example: execution_time
in: query
name: sort_by
schema:
default: create_time
enum:
- create_time
- execution_time
type: string
- description: Sort direction (asc = ascending, desc = descending)
in: query
name: sort_order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: |
Opaque cursor for keyset pagination. Pass the `next_cursor` value
from a previous response to fetch the next page.
Cursor pagination is supported only when `sort_by=create_time`
(default). If `sort_by=execution_time`, `after` is ignored and
offset/limit pagination is used.
Cursors are opaque base64url payloads — clients should treat them
as strings and not parse the contents.
example: eyJzIjoiY3JlYXRlX3RpbWUiLCJ2IjoiMTcxNjIwMDAwMDAwMDAwMCIsImlkIjoiYTFiMmMzZDQtZTVmNi03YTg5LWIwYzEtZDJlM2Y0YTViNmM3In0
in: query
name: after
schema:
type: string
- deprecated: true
description: 'Pagination offset (0-based). Deprecated: prefer cursor-based pagination via `after`.'
in: query
name: offset
schema:
default: 0
minimum: 0
type: integer
- description: Maximum items per page (1-1000)
in: query
name: limit
schema:
default: 100
maximum: 1000
minimum: 1
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/JobsListResponse'
description: Success - Jobs retrieved
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Bad request (e.g. malformed pagination cursor).
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: List jobs with pagination and filtering
tags:
- workflow
/api/jobs/{job_id}:
get:
description: |
Retrieve complete details for a specific job including workflow and outputs.
Used for detail views, workflow re-execution, and debugging.
operationId: getJobDetail
parameters:
- description: Job identifier (UUID)
in: path
name: job_id
required: true
schema:
format: uuid
type: string
- description: |
When present, each output item in the response receives a `short_url` field containing a short link for that asset. Omit this parameter (the default) to receive a response identical to the no-param baseline. The value selects the link's lifetime and auth model: use `ephemeral_tool_chain` for short-lived (≤5 minute) machine-to-machine handoffs — these are public bearer links where the link ID itself is the credential, so anyone holding the link can resolve it (intended for pasting into an agent/MCP tool chain); use `default` for durable (30 day) human-revisitable links, which are owner-gated and resolvable only by the authenticated owner. Links are always minted under the authenticated request owner's identity; the auth model is selected by the server and is never settable by the caller.
in: query
name: short_link
schema:
enum:
- ephemeral_tool_chain
- default
type: string
x-runtime:
- cloud
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/JobDetailResponse'
description: Success - Job details retrieved
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Forbidden - Job does not belong to user
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Job not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get full job details
tags:
- workflow
/api/jobs/{job_id}/assets:
get:
description: |
Retrieve a paginated list of the assets produced by a specific job,
enriched with the per-output node context (`node_id`, `output_key`,
`output_index`) correlated from the job's execution outputs by content
hash. Unlike `GET /api/assets?job_ids={id}`, this endpoint is scoped to a
single job and carries node-level placement, making it suited to job
output views rather than the general asset browser. Returns an empty
`assets` array for jobs that produced no assets.
operationId: getJobAssets
parameters:
- description: Job identifier (UUID)
in: path
name: job_id
required: true
schema:
format: uuid
type: string
- description: Maximum number of assets to return (1-500)
in: query
name: limit
schema:
default: 20
maximum: 500
minimum: 1
type: integer
- description: Number of assets to skip for pagination
in: query
name: offset
schema:
default: 0
minimum: 0
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/JobAssetsResponse'
description: Success - Job assets returned
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request parameters
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Job not found or does not belong to the user
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: List a job's output assets
tags:
- workflow
/api/jobs/{job_id}/cancel:
post:
description: |
Cancel a specific job for the authenticated user.
Idempotent: a job that is already in a terminal state (completed, failed,
cancelled) or already cancelling is treated as a successful no-op and
returns 200. Only truly missing or cross-user jobs return 404.
operationId: cancelJob
parameters:
- description: Job identifier (UUID)
in: path
name: job_id
required: true
schema:
format: uuid
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/JobCancelResponse'
description: Success - Cancel request accepted (or job was already terminal)
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Bad Request - job_id is not a valid UUID (emitted by request validation before the handler runs)
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Job not found for this user
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error - cancellation failed
summary: Cancel a job
tags:
- workflow
/api/jobs/cancel:
post:
description: |
Cancel one or more jobs for the authenticated user in a single request.
State-agnostic: cancels both pending and running jobs (both transition to
the cancelled state via the same mechanism as the single-job endpoint).
Idempotent per job: a job already in a terminal or cancelling state is a
no-op and simply will not appear in the returned `cancelled` list.
Fail-fast on unknown IDs: if any provided job ID does not exist for this
user, the request returns 404 and no jobs are cancelled. This surfaces
bad IDs to the caller rather than silently dropping them.
This is the canonical batch-cancel endpoint. The delete operation on
POST /api/queue is deprecated in favour of this.
operationId: cancelJobs
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/JobsCancelRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/JobsCancelResponse'
description: Success - cancel requests dispatched (or jobs were already terminal)
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Bad Request - job_ids is missing, empty, exceeds the maximum count, or contains an invalid UUID
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: One or more job IDs not found for this user (no jobs cancelled)
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error - cancellation failed
summary: Cancel multiple jobs
tags:
- workflow
/api/node_replacements:
get:
description: |
Returns mappings of unsupported node class names to their cloud-installed replacements.
Used by the frontend to offer "Quick Fix" when a workflow contains missing nodes.
operationId: getNodeReplacements
responses:
"200":
content:
application/json:
schema:
additionalProperties: true
type: object
description: Success - Node replacement mappings
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
security: []
summary: Get node replacement mappings
tags:
- node
/api/object_info:
get:
description: Returns information about all available nodes
operationId: getNodeInfo
responses:
"200":
content:
application/json:
schema:
additionalProperties:
$ref: '#/components/schemas/NodeInfo'
type: object
description: Success
summary: Get all node information
tags:
- node
/api/prompt:
get:
description: Returns information about the current prompt in the execution queue
operationId: getPromptInfo
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/PromptInfo'
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get information about current prompt execution
tags:
- workflow
post:
description: |
Submit a workflow to be executed by the backend.
The workflow is a JSON object describing the nodes and their connections.
operationId: executePrompt
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PromptRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/PromptResponse'
description: Success - Prompt accepted
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/PromptErrorResponse'
description: Invalid prompt
"402":
content:
application/json:
schema:
$ref: '#/components/schemas/PromptErrorResponse'
description: Payment required - Insufficient credits
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/PromptErrorResponse'
description: Workspace governance policy blocks one or more partner providers (error.type PARTNER_NODE_DISABLED; error.class_types lists the offending nodes, error.providers the disabled providers)
"413":
content:
application/json:
schema:
$ref: '#/components/schemas/PromptErrorResponse'
description: Workflow JSON too large
"429":
content:
application/json:
schema:
$ref: '#/components/schemas/PromptErrorResponse'
description: 'Retryable backpressure. Two distinct causes, disambiguated by the body''s `error.type`, NOT by parsing `error.message`: `PAYMENT_REQUIRED` / `FREE_TIER_UNAVAILABLE` / `FREE_TIER_EXHAUSTED` / `PARTNER_NODE_PAYMENT_REQUIRED` (a billing gate - retrying without paying never succeeds), or `QUEUE_LIMIT` (this workspace''s bounded job queue is full - retrying after some queued jobs complete will succeed).'
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/PromptErrorResponse'
description: Internal server error
"503":
content:
application/json:
schema:
$ref: '#/components/schemas/PromptErrorResponse'
description: Service unavailable
summary: Submit a workflow for execution
tags:
- workflow
/api/queue:
get:
description: Returns information about running and pending items in the queue
operationId: getQueueInfo
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/QueueInfo'
description: Success
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request parameters
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request parameters
summary: Get queue information
tags:
- queue
post:
deprecated: true
description: |
Deprecated. Prefer the jobs-namespace cancel endpoints:
POST /api/jobs/cancel for cancelling jobs by ID, and
POST /api/jobs/{job_id}/cancel for a single job.
Cancel specific jobs by ID (the `delete` field) or clear all pending
jobs in the queue (the `clear` field). Despite the `delete` naming, this
does not delete anything — listed jobs transition to the cancelled state,
and `delete` cancels both pending and running jobs (not pending-only as
previously documented). Job-by-ID cancellation is superseded by
POST /api/jobs/cancel; `clear` has no jobs-namespace replacement yet.
operationId: manageQueue
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/QueueManageRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/QueueManageResponse'
description: Success
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request parameters
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Manage queue operations
tags:
- queue
/api/settings:
get:
description: Returns all settings for the authenticated user
operationId: getAllSettings
responses:
"200":
content:
application/json:
schema:
additionalProperties: true
description: User settings as key-value pairs
type: object
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
summary: Get all user settings
tags:
- settings
post:
description: Update multiple settings (merge with existing)
operationId: updateMultipleSettings
requestBody:
content:
application/json:
schema:
additionalProperties: true
description: Settings to update as key-value pairs
type: object
text/plain:
schema:
description: JSON string of settings to update
type: string
required: true
responses:
"200":
content:
application/json:
schema:
additionalProperties: true
description: Updated user settings
type: object
description: Success
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
summary: Update multiple settings
tags:
- settings
/api/settings/{id}:
get:
description: Returns a specific setting value by its id
operationId: getSettingById
parameters:
- description: Setting id to retrieve
in: path
name: id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
description: Setting value response
properties:
value:
description: The setting value
type: object
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Setting not found
summary: Get a specific setting by id
tags:
- settings
post:
description: Update a specific setting by its id
operationId: updateSettingById
parameters:
- description: Setting id to update
in: path
name: id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
description: New value for the setting
text/plain:
schema:
description: JSON string of the new setting value
type: string
required: true
responses:
"200":
content:
application/json:
schema:
description: Updated setting value response
properties:
value:
description: The updated setting value
type: object
description: Success
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
summary: Update a specific setting by id
tags:
- settings
/api/system_stats:
get:
description: Returns system statistics including ComfyUI version, device info, and system resources
operationId: getSystemStats
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/SystemStatsResponse'
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
security: []
summary: Get system statistics
tags:
- system
/api/tags:
get:
description: |
Retrieves a list of all tags used across assets.
Includes usage counts and filtering options.
operationId: listTags
parameters:
- description: Filter tags by prefix
in: query
name: prefix
schema:
type: string
- description: Maximum number of tags to return (1-1000)
in: query
name: limit
schema:
default: 100
maximum: 1000
minimum: 1
type: integer
- description: Number of tags to skip for pagination
in: query
name: offset
schema:
default: 0
minimum: 0
type: integer
- description: Sort order for tags
in: query
name: order
schema:
default: count_desc
enum:
- count_desc
- name_asc
type: string
- description: Include tags with zero usage count
in: query
name: include_zero
schema:
default: false
type: boolean
- description: Whether to include public/shared assets when counting tags
in: query
name: include_public
schema:
default: true
type: boolean
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/ListTagsResponse'
description: Tags retrieved successfully
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request parameters
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: List all tags
tags:
- file
/api/tasks:
get:
description: |
Retrieve a paginated list of background tasks for the authenticated user.
Supports filtering by task type, status, and creation time.
operationId: listTasks
parameters:
- description: Filter by task type name (exact match)
example: model_upload
in: query
name: task_name
schema:
type: string
- description: Filter by idempotency key (exact match). For best performance, specify task_name as well.
example: upload-model-abc123
in: query
name: idempotency_key
schema:
type: string
- description: Filter by one or more statuses (comma-separated)
example: created,running
in: query
name: status
schema:
type: string
- description: Filter tasks created after this timestamp (RFC3339 format)
example: "2024-01-01T00:00:00Z"
in: query
name: created_after
schema:
format: date-time
type: string
- description: Filter tasks created before this timestamp (RFC3339 format)
example: "2024-12-31T23:59:59Z"
in: query
name: created_before
schema:
format: date-time
type: string
- description: Sort direction (asc = ascending, desc = descending by create_time)
in: query
name: sort_order
schema:
default: desc
enum:
- asc
- desc
type: string
- description: Pagination offset (0-based)
in: query
name: offset
schema:
default: 0
minimum: 0
type: integer
- description: Maximum items per page (1-100)
in: query
name: limit
schema:
default: 20
maximum: 100
minimum: 1
type: integer
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/TasksListResponse'
description: Success - Tasks retrieved
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"422":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error - Invalid filter values
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: List background tasks
tags:
- task
/api/tasks/{task_id}:
get:
description: |
Retrieve full details for a specific background task.
operationId: getTask
parameters:
- description: Task identifier (UUID)
in: path
name: task_id
required: true
schema:
format: uuid
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/TaskResponse'
description: Success - Task details retrieved
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized - Authentication required
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Task not found (also returned for ownership failures to avoid leaking task existence)
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get task details
tags:
- task
/api/upload/image:
post:
description: |
Upload an image file to cloud storage.
Image limits:
- Maximum file size: 50 MB
- Maximum width/height per edge: 16384 px
- Maximum total pixel count: 64 megapixels (67108864 pixels)
Uploads that exceed any of these limits are rejected with HTTP 400.
operationId: uploadImage
requestBody:
content:
multipart/form-data:
schema:
properties:
image:
description: The image file to upload
format: binary
type: string
overwrite:
description: Whether to overwrite existing file (true/false)
type: string
subfolder:
description: Optional subfolder path
type: string
type:
description: Upload type (defaults to "output")
type: string
required:
- image
type: object
required: true
responses:
"200":
content:
application/json:
schema:
properties:
name:
description: Filename of the uploaded image
type: string
subfolder:
description: Subfolder path where image was saved
type: string
type:
description: Type of upload (e.g., "output")
type: string
type: object
description: Image uploaded successfully
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Bad request
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Upload an image file
tags:
- file
/api/upload/mask:
post:
description: |
Upload a mask image to be applied to an existing image.
Image limits apply to both the uploaded mask and the referenced
original image:
- Maximum file size: 50 MB
- Maximum width/height per edge: 16384 px
- Maximum total pixel count: 64 megapixels (67108864 pixels)
Uploads that exceed any of these limits are rejected with HTTP 400.
operationId: uploadMask
requestBody:
content:
multipart/form-data:
schema:
properties:
image:
description: The mask image file to upload
format: binary
type: string
original_ref:
description: JSON string containing reference to the original image
type: string
required:
- image
- original_ref
type: object
required: true
responses:
"200":
content:
application/json:
schema:
properties:
name:
description: Filename of the uploaded mask
type: string
subfolder:
description: Subfolder path where mask was saved
type: string
type:
description: Type of upload (e.g., "output")
type: string
type: object
description: Mask uploaded successfully
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Bad request
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Upload a mask image
tags:
- file
/api/user:
get:
description: Returns information about the currently authenticated user
operationId: getUser
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/UserResponse'
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
summary: Get current user information
tags:
- user
/api/userdata:
get:
description: Returns a list of user data files in the specified directory, optionally recursively and with full metadata.
operationId: getUserdata
parameters:
- description: The directory to list files from.
in: query
name: dir
schema:
type: string
- description: Whether to list files recursively.
in: query
name: recurse
schema:
default: false
type: boolean
- description: Whether to split file information by type.
in: query
name: split
schema:
default: false
type: boolean
- description: Whether to return full file metadata.
in: query
name: full_info
schema:
default: false
type: boolean
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/GetUserDataResponseFull'
description: A list of user data files.
"400":
content:
text/plain:
schema:
type: string
description: Bad request (e.g., invalid filename).
"401":
content:
text/plain:
schema:
type: string
description: Unauthorized.
"404":
content:
text/plain:
schema:
type: string
description: File not found or invalid path.
"500":
content:
text/plain:
schema:
type: string
description: General error
summary: List user data files
tags:
- user
/api/userdata/{file}:
delete:
description: |
Delete a user data file from the database. The file parameter should be
the relative path within the user's data directory.
operationId: deleteUserdataFile
parameters:
- description: The file path to delete (URL encoded if necessary).
in: path
name: file
required: true
schema:
type: string
responses:
"204":
description: File deleted successfully (No Content).
"401":
content:
text/plain:
schema:
type: string
description: Unauthorized.
"404":
content:
text/plain:
schema:
type: string
description: File not found.
"500":
content:
text/plain:
schema:
type: string
description: Internal server error.
summary: Delete a user data file
tags:
- user
get:
description: Returns the requested user data file if it exists.
operationId: getUserdataFile
parameters:
- description: The filename of the user data to retrieve.
in: path
name: file
required: true
schema:
type: string
responses:
"200":
content:
application/octet-stream:
schema:
format: binary
type: string
description: Successfully retrieved the file.
"400":
content:
text/plain:
schema:
type: string
description: Bad request (e.g., invalid filename).
"401":
content:
text/plain:
schema:
type: string
description: Unauthorized.
"404":
content:
text/plain:
schema:
type: string
description: File not found or invalid path.
"500":
content:
text/plain:
schema:
type: string
description: General error
summary: Get user data file
tags:
- user
post:
description: |
Upload a file to a user's data directory. Optional query parameters allow
control over overwrite behavior and response detail.
operationId: postUserdataFile
parameters:
- description: The target file path (URL encoded if necessary).
in: path
name: file
required: true
schema:
type: string
- description: If "false", prevents overwriting existing files. Defaults to "true".
in: query
name: overwrite
schema:
default: "true"
enum:
- "true"
- "false"
type: string
- description: If "true", returns detailed file info; if "false", returns only the relative path.
in: query
name: full_info
schema:
default: "false"
enum:
- "true"
- "false"
type: string
requestBody:
content:
application/octet-stream:
schema:
format: binary
type: string
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/UserDataResponseFull'
description: File uploaded successfully.
"400":
content:
text/plain:
schema:
type: string
description: Missing or invalid 'file' parameter.
"401":
content:
text/plain:
schema:
type: string
description: Unauthorized.
"403":
content:
text/plain:
schema:
type: string
description: The requested path is not allowed.
"409":
content:
text/plain:
schema:
type: string
description: File already exists and overwrite is set to false.
"500":
content:
text/plain:
schema:
type: string
description: General error
summary: Upload or update a user data file
tags:
- user
/api/userdata/{file}/move/{dest}:
post:
description: |
Move or rename a file within a user's data directory, with options for
controlling overwrite behavior and response format.
operationId: moveUserdataFile
parameters:
- description: The source file path (URL encoded if necessary).
in: path
name: file
required: true
schema:
type: string
- description: The destination file path (URL encoded if necessary).
in: path
name: dest
required: true
schema:
type: string
- description: If "false", prevents overwriting existing files. Defaults to "true".
in: query
name: overwrite
schema:
default: "true"
enum:
- "true"
- "false"
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/UserDataResponseFull'
description: File moved successfully.
"400":
content:
text/plain:
schema:
type: string
description: Missing or invalid parameters.
"401":
content:
text/plain:
schema:
type: string
description: Unauthorized.
"404":
content:
text/plain:
schema:
type: string
description: Source file not found.
"409":
content:
text/plain:
schema:
type: string
description: Destination file already exists and overwrite is set to false.
"500":
content:
text/plain:
schema:
type: string
description: General error
summary: Move or rename a user data file
tags:
- user
/api/userdata/{file}/publish:
get:
description: Returns the publish status and share info for a workflow identified by its userdata path.
operationId: getUserdataFilePublish
parameters:
- description: The workflow file path within the user's data directory (URL encoded if necessary).
in: path
name: file
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowPublishInfo'
description: Publish info (publish_time is null if never published)
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Workflow not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get publish info for a workflow file
tags:
- workflows
post:
description: Creates a new published_workflow record from the latest version and snapshots the provided assets.
operationId: postUserdataFilePublish
parameters:
- description: The workflow file path within the user's data directory (URL encoded if necessary).
in: path
name: file
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PublishWorkflowAssetsRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowPublishInfo'
description: Workflow published
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Bad request
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Workflow not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Publish a workflow file
tags:
- workflows
/api/users:
get:
description: |
ComfyUI legacy users endpoint. Returns information about how user
data is stored. In cloud this is always server-managed, so callers
receive a constant response indicating server-side storage.
operationId: getUsersInfo
responses:
"200":
content:
application/json:
schema:
properties:
migrated:
description: Whether user data has been migrated (always true in cloud)
type: boolean
storage:
description: Where user data is stored (always "server" in cloud)
type: string
required:
- storage
- migrated
type: object
description: Userdata storage information
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
summary: ComfyUI userdata storage info
tags:
- user
/api/vhs/queryvideo:
get:
description: |
VHS custom node endpoint that returns metadata about a video file
(frame count, fps, resolution, duration). Currently returns default
placeholder values; real ffprobe integration is a follow-up.
operationId: getVhsQueryVideo
parameters:
- description: Name of the video file to query
in: query
name: filename
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
properties:
source:
description: Source video metadata
properties:
duration:
description: Duration in seconds
type: number
fps:
description: Frames per second
type: number
frames:
description: Total frame count
type: integer
size:
description: '[width, height] in pixels'
items:
type: integer
maxItems: 2
minItems: 2
type: array
required:
- size
- fps
- frames
- duration
type: object
required:
- source
type: object
description: Video metadata
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: |
Missing required query parameter. Produced by the oapi-codegen
wrapper via echo.NewHTTPError; the custom Echo HTTPErrorHandler
normalizes it to the standard ErrorResponse {code, message} shape
(BE-1178).
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
security:
- ApiKeyAuth: []
- BearerAuth: []
- CookieAuth: []
summary: Query VHS video metadata
tags:
- file
/api/view:
get:
description: |
Retrieve and view a file from the ComfyUI file system.
This endpoint is typically used to view generated images or other output files.
Cookie auth is allowed on this endpoint because it's used by img/video tags in browsers.
operationId: viewFile
parameters:
- description: Name of the file to view
in: query
name: filename
required: true
schema:
example: ComfyUI_00004_.png
type: string
- description: Subfolder path where the file is located
in: query
name: subfolder
schema:
example: tests/foo/bar
type: string
- description: Type of file (e.g., output, input, temp)
in: query
name: type
schema:
example: output
type: string
- description: Full path to the file (used for temp files)
in: query
name: fullpath
schema:
type: string
- description: Format of the file
in: query
name: format
schema:
type: string
- description: Frame rate for video files
in: query
name: frame_rate
schema:
type: integer
- description: Workflow identifier
in: query
name: workflow
schema:
type: string
- description: Timestamp parameter
in: query
name: timestamp
schema:
example: 1234567890
type: integer
- description: |
Image channel to extract from PNG images.
- 'rgb': Return only RGB channels (alpha set to fully opaque)
- 'a' or 'alpha': Return alpha channel as grayscale image
- If not specified, return original image unchanged via redirect
in: query
name: channel
schema:
example: rgb
type: string
- description: |
Maximum dimension (width or height) to resize the image to, preserving aspect ratio.
The image is fit within a res x res box. Returns a JPEG thumbnail.
Only applies to raster image files (PNG, JPEG, WebP, GIF).
in: query
name: res
schema:
example: 256
maximum: 1024
minimum: 64
type: integer
responses:
"200":
content:
image/jpeg:
schema:
description: Resized JPEG thumbnail (returned when res parameter is used)
format: binary
type: string
image/png:
schema:
description: Processed PNG image with extracted channel
format: binary
type: string
description: Success - File content returned (used when channel or res parameter is present)
"302":
description: Redirect to GCS signed URL
headers:
Cache-Control:
description: Cache directive for the redirect response
schema:
type: string
Location:
description: Signed URL to access the file in GCS
schema:
type: string
Vary:
description: Headers that affect response caching
schema:
type: string
"400":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Invalid request parameters
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: File not found or unauthorized
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
security:
- ApiKeyAuth: []
- BearerAuth: []
- CookieAuth: []
summary: View a file
tags:
- file
/api/workflow_templates:
get:
description: Returns available workflow templates
operationId: getWorkflowTemplates
responses:
"200":
content:
application/json:
schema:
description: Empty object for workflow templates
type: object
description: Success
security: []
summary: Get available workflow templates
tags:
- workflow
/api/workflows:
get:
description: Returns a paginated list of workflows for the authenticated user in the current workspace.
operationId: listWorkflows
parameters:
- in: query
name: limit
schema:
default: 20
maximum: 100
type: integer
- in: query
name: offset
schema:
default: 0
type: integer
- description: Search workflows by name (case-insensitive substring match)
in: query
name: name
schema:
type: string
- description: Filter by default view type
in: query
name: default_view
schema:
enum:
- workflow
- app
type: string
- description: Sort field
in: query
name: sort
schema:
default: create_time
enum:
- create_time
- update_time
- name
type: string
- description: Sort order
in: query
name: order
schema:
default: desc
enum:
- asc
- desc
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowListResponse'
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: List workflows
tags:
- workflows
post:
description: Creates a new workflow with its first version.
operationId: createWorkflow
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWorkflowRequest'
required: true
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowResponse'
description: Workflow created successfully
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"422":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Create a new workflow
tags:
- workflows
/api/workflows/{workflow_id}:
delete:
description: Soft-deletes a workflow.
operationId: deleteWorkflow
parameters:
- description: The UUID of the workflow to delete.
in: path
name: workflow_id
required: true
schema:
type: string
responses:
"204":
description: Workflow deleted successfully
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Workflow not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Delete workflow
tags:
- workflows
get:
description: Retrieves workflow metadata by ID.
operationId: getWorkflow
parameters:
- description: The UUID of the workflow.
in: path
name: workflow_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowResponse'
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Forbidden
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Workflow not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get workflow
tags:
- workflows
patch:
description: Updates mutable workflow metadata (name, description, default_view).
operationId: updateWorkflow
parameters:
- description: The UUID of the workflow to update.
in: path
name: workflow_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateWorkflowRequest'
required: true
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowResponse'
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Workflow not found
"422":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Update workflow metadata
tags:
- workflows
/api/workflows/{workflow_id}/content:
get:
description: Retrieves the latest version of a workflow and its JSON content.
operationId: getWorkflowContent
parameters:
- description: The UUID of the workflow whose content should be retrieved.
in: path
name: workflow_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowVersionContentResponse'
description: Success
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Forbidden
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Workflow not found
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get workflow content
tags:
- workflows
/api/workflows/{workflow_id}/fork:
post:
description: Creates a new workflow by forking from an existing version.
operationId: forkWorkflow
parameters:
- description: The UUID of the source workflow to fork from.
in: path
name: workflow_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ForkWorkflowRequest'
required: true
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowResponse'
description: Workflow forked successfully
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Forbidden
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Source workflow or version not found
"422":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Fork a workflow
tags:
- workflows
/api/workflows/{workflow_id}/versions:
post:
description: Creates a new workflow version with updated workflow JSON. Uses optimistic concurrency via base_version.
operationId: createWorkflowVersion
parameters:
- description: The UUID of the workflow to create a new version for.
in: path
name: workflow_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateWorkflowVersionRequest'
required: true
responses:
"201":
content:
application/json:
schema:
$ref: '#/components/schemas/WorkflowVersionResponse'
description: Version created successfully
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"403":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Forbidden - not the workflow owner
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Workflow not found
"409":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Version conflict - base_version does not match latest
"422":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Validation error
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Create a new version
tags:
- workflows
/api/workflows/published/{share_id}:
get:
description: |
Returns the published workflow details including the status of each
published asset relative to the caller's library. Authentication is required.
operationId: getPublishedWorkflow
parameters:
- description: The share ID of the published workflow.
in: path
name: share_id
required: true
schema:
type: string
responses:
"200":
content:
application/json:
schema:
$ref: '#/components/schemas/PublishedWorkflowDetail'
description: Published workflow details with asset statuses
"401":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Unauthorized
"404":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Share not found
"413":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Workflow JSON too large
"500":
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
description: Internal server error
summary: Get a published workflow by share ID
tags:
- workflows
/health:
get:
description: |
Returns `200 OK` if the database is reachable and dynamic config has
loaded, otherwise `503 Service Unavailable`. Used by the GKE ingress
for health checks. Response body is plain text for probe simplicity.
operationId: getHealth
responses:
"200":
content:
text/plain:
schema:
example: OK
type: string
description: Service is healthy
"503":
content:
text/plain:
schema:
example: Service Unavailable
type: string
description: Service is unhealthy
security: []
summary: Health probe for Kubernetes readiness/liveness
tags:
- system
/internal/folder_paths:
get:
description: Returns the filesystem paths ComfyUI loads models and assets from, keyed by folder type.
operationId: getInternalFolderPaths
responses:
"200":
content:
application/json:
schema:
additionalProperties:
items:
items:
type: string
type: array
type: array
description: Map of folder type name to list of path entries
type: object
description: Dictionary of folder type to paths
summary: Get configured folder paths
/internal/logs:
get:
description: Returns ComfyUI log entries from the in-memory log buffer.
operationId: getInternalLogs
responses:
"200":
content:
text/plain:
schema:
type: string
description: Log text
summary: Get server logs as text
/internal/logs/raw:
get:
description: Returns the raw ComfyUI log buffer plus size metadata.
operationId: getInternalLogsRaw
responses:
"200":
content:
application/json:
schema:
properties:
entries:
items:
properties:
m:
description: Message
type: string
t:
description: Timestamp
type: number
type: object
type: array
size:
properties:
cols:
type: integer
rows:
type: integer
type: object
type: object
description: Structured log data
summary: Get raw structured log entries
/internal/logs/subscribe:
patch:
description: Subscribes or unsubscribes the current client from live log streaming over the WebSocket.
operationId: subscribeToLogs
requestBody:
content:
application/json:
schema:
properties:
clientId:
description: WebSocket client ID
type: string
enabled:
description: Enable or disable log streaming for this client
type: boolean
required:
- clientId
- enabled
type: object
required: true
responses:
"200":
description: Subscription updated
summary: Subscribe or unsubscribe a WebSocket client to log streaming
security:
- ApiKeyAuth: []
- BearerAuth: []
servers:
- description: Default ComfyUI server
url: /
tags:
- description: Workflow execution and management
name: workflow
- description: Node information
name: node
- description: File operations
name: file
- description: User settings management
name: settings
- description: User feedback management
name: feedback
- description: System operations and monitoring
name: system
- description: User information and management
name: user
- description: Background task management
name: task
- description: Workspace billing and subscription management
name: billing
- description: Workflow storage and version management
name: workflows
- description: Job queue state and control
name: queue
- description: Job lifecycle queries
name: job