mirror of
https://github.com/comfyanonymous/ComfyUI.git
synced 2026-06-03 12:57:25 +08:00
4947 lines
200 KiB
YAML
4947 lines
200 KiB
YAML
components:
|
|
schemas:
|
|
Asset:
|
|
description: Represents a user-owned asset (image, video, or other generated output).
|
|
properties:
|
|
asset_hash:
|
|
description: Blake3 hash of the asset content
|
|
pattern: ^blake3:[a-f0-9]{64}$
|
|
type: string
|
|
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
|
|
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
|
|
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
|
|
prompt_id:
|
|
deprecated: true
|
|
description: 'Deprecated: use job_id instead. ID of the prompt that created this asset, if available'
|
|
format: uuid
|
|
nullable: true
|
|
type: string
|
|
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:
|
|
asset_hash:
|
|
description: Blake3 hash of the asset content
|
|
pattern: ^blake3:[a-f0-9]{64}$
|
|
type: string
|
|
display_name:
|
|
description: Display name of the asset. Mirrors name for backwards compatibility.
|
|
nullable: true
|
|
type: string
|
|
id:
|
|
description: Asset ID
|
|
format: uuid
|
|
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
|
|
BindingErrorResponse:
|
|
description: Error shape returned when request binding or validation fails before the handler runs.
|
|
properties:
|
|
message:
|
|
type: string
|
|
required:
|
|
- message
|
|
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
|
|
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
|
|
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_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_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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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
|
|
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: Offset/limit-based pagination metadata included in list responses.
|
|
properties:
|
|
has_more:
|
|
description: Whether more items are available beyond this page
|
|
type: boolean
|
|
limit:
|
|
description: Items per page
|
|
minimum: 1
|
|
type: integer
|
|
offset:
|
|
description: Current offset (0-based)
|
|
minimum: 0
|
|
type: integer
|
|
total:
|
|
description: Total number of items matching filters
|
|
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 PENDING job IDs to cancel
|
|
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
|
|
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:
|
|
- description: Filter assets that have ALL of these tags
|
|
explode: false
|
|
in: query
|
|
name: include_tags
|
|
schema:
|
|
items:
|
|
type: string
|
|
type: array
|
|
style: form
|
|
- description: Exclude assets that have ANY of these tags
|
|
explode: false
|
|
in: query
|
|
name: exclude_tags
|
|
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 exact content hash
|
|
in: query
|
|
name: asset_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: |
|
|
Uploads a new asset to the system with associated metadata.
|
|
Supports two upload methods:
|
|
1. Direct file upload (multipart/form-data)
|
|
2. URL-based upload (application/json with source: "url")
|
|
|
|
If an asset with the same hash already exists, returns the existing asset.
|
|
operationId: uploadAsset
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
name:
|
|
description: Display name for the asset (used to determine file extension)
|
|
type: string
|
|
preview_id:
|
|
description: Optional preview asset ID
|
|
format: uuid
|
|
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
|
|
type: array
|
|
url:
|
|
description: HTTP/HTTPS URL to download the asset from
|
|
format: uri
|
|
type: string
|
|
user_metadata:
|
|
additionalProperties: true
|
|
description: Custom metadata to store with the asset
|
|
type: object
|
|
required:
|
|
- url
|
|
- name
|
|
type: object
|
|
multipart/form-data:
|
|
schema:
|
|
properties:
|
|
file:
|
|
description: The asset file to upload
|
|
format: binary
|
|
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: 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
|
|
type: array
|
|
user_metadata:
|
|
description: Custom JSON metadata as a string
|
|
type: string
|
|
required:
|
|
- file
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetCreated'
|
|
description: Asset created successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request (bad file, invalid URL, invalid content type, etc.)
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Source URL requires authentication or access denied
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Source URL not found
|
|
"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: Download failed due to network error or timeout
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Upload a new asset
|
|
tags:
|
|
- file
|
|
/api/assets/{id}:
|
|
delete:
|
|
description: |
|
|
Deletes an asset and its content from storage.
|
|
Both the database record and storage content are deleted.
|
|
operationId: deleteAsset
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"204":
|
|
description: Asset 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., workflow version)
|
|
"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 the dedicated PUT /api/assets/{id}/tags endpoint.
|
|
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)
|
|
"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: Update asset metadata
|
|
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
|
|
put:
|
|
description: Adds and removes tags from an asset in a single operation
|
|
operationId: updateAssetTags
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: At least one of add or remove must contain items. Empty arrays are allowed when the other array has items.
|
|
minProperties: 1
|
|
properties:
|
|
add:
|
|
description: Tags to add to the asset. Can be empty if remove has items.
|
|
items:
|
|
type: string
|
|
type: array
|
|
remove:
|
|
description: Tags to remove from the asset. Can be empty if add has items.
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TagsModificationResponse'
|
|
description: Tags updated 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: Reserved tag validation error
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Update asset tags
|
|
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: Hash of the existing asset. Supports Blake3 (blake3:) or SHA256 (sha256:) formats
|
|
pattern: ^(blake3|sha256):[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:
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetCreated'
|
|
description: Asset reference created successfully
|
|
"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
|
|
"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:
|
|
- description: Filter assets that have ALL of these tags
|
|
explode: false
|
|
in: query
|
|
name: include_tags
|
|
schema:
|
|
items:
|
|
type: string
|
|
type: array
|
|
style: form
|
|
- description: Exclude assets that have ANY of these tags
|
|
explode: false
|
|
in: query
|
|
name: exclude_tags
|
|
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/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.
|
|
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: []
|
|
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.
|
|
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: []
|
|
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:
|
|
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:
|
|
description: |
|
|
Cancel all currently RUNNING jobs for the authenticated user.
|
|
This will interrupt any job that is currently in 'in_progress' status.
|
|
Note: This endpoint only affects running jobs. To cancel pending jobs, use /api/queue.
|
|
operationId: interruptJob
|
|
responses:
|
|
"200":
|
|
description: Success - Job interrupted or no running 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 currently running jobs
|
|
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: Pagination offset (0-based)
|
|
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
|
|
"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
|
|
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}/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/BindingErrorResponse'
|
|
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/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
|
|
"429":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptErrorResponse'
|
|
description: Payment required - User has not paid
|
|
"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
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
summary: Get queue information
|
|
tags:
|
|
- queue
|
|
post:
|
|
description: |
|
|
Cancel specific PENDING jobs by ID or clear all pending jobs in the queue.
|
|
Note: This endpoint only affects pending jobs. To cancel running jobs, use /api/interrupt.
|
|
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/BindingErrorResponse'
|
|
description: |
|
|
Missing required query parameter. Produced by the oapi-codegen
|
|
wrapper via echo.NewHTTPError, so the body shape matches Echo's
|
|
default HTTPError serialization rather than ErrorResponse.
|
|
"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: Workflow storage and version management
|
|
name: workflows
|
|
- description: Job queue state and control
|
|
name: queue
|
|
- description: Job lifecycle queries
|
|
name: job
|