mirror of
https://github.com/comfyanonymous/ComfyUI.git
synced 2026-07-11 00:47:14 +08:00
55a15f87ce
* feat(assets): add namespaced model type tags * fix(assets): mark path-derived upload tags automatic * fix(assets): merge duplicate scan specs * test(assets): make duplicate path normalization portable * feat(assets): add loader_path as the authoritative loader locator (#14796) * fix(assets): filter model_type tags by bucket extension sets Buckets sharing a base directory (e.g. diffusion_models and a custom unet_gguf) tagged every file in the directory regardless of whether the bucket could load it, so .safetensors files were tagged model_type:unet_gguf and vice versa. Carry each bucket's registered extension set through get_comfy_models_folders and only emit a model_type tag when the file extension matches, keeping the empty-set match-all convention from folder_paths.filter_files_extensions. Files under a model base matching no bucket now keep only the models tag instead of every directory-matching model_type tag. * feat(assets): replace response file_path with persisted loader_path The old file_path response field was a namespaced storage locator (models/checkpoints/foo.safetensors): not an absolute path, not unique identity, and not the value a loader consumes. Nothing needs that shape on the wire (hash/ID-based locating is the long-term direction), so it is dropped rather than renamed; the storage-root matching stays internal, powering display_name. What loaders DO need is the in-root loader path (category dropped: models/checkpoints/foo/bar.safetensors -> foo/bar.safetensors). Serve it as a first-class loader_path field, persisted on asset_references (migration 0006) and written by every ingest pipeline at insert, so responses read the column verbatim. Like the model_type tags, loader_path is a seed-time derivative of the model folder registry, maintained by the same scan lifecycle (new files seed fresh values, pruning retires rows whose bucket disappeared). Rows predating the column serve a null loader_path; databases from before this stack already need recreating for the base branch's tag changes. loader_path resolves every registered base including extra_model_paths entries; display_name only the canonical storage roots. A file can therefore be loadable with no display name (extra-path models) or the reverse (unregistered files under the models root), and loader_path is null exactly when no loader can resolve the file. * test(assets): lock loader_path matrix (asymmetry, null, persist/read) Cover the behaviour that has no production change but is easy to regress: the extra-path asymmetry (loadable but no storage namespace), null loader_path persistence for orphan files, and the response reading the stored column with a compute fallback for un-backfilled rows. * fix(assets): persist subfolder-qualified loader_path for ingested outputs ingest_existing_file built its seed spec with the file's basename, so outputs saved into a subfolder persisted loader_path (and the user_metadata filename that preview URLs split for their subfolder param) as just the basename: the served locator pointed at a file that does not exist at that path. Scanner and seeder specs already derive fname via compute_loader_path; use the same derivation here. * fix(assets): only extension-matching buckets contribute a loader_path The model-base match in get_asset_category_and_relative_path ignored each bucket's extension set, so a file inside a registered base whose extension the bucket cannot load (e.g. a .txt uploaded into model_type:checkpoints) advertised a loader_path that no loader list would ever resolve, while the tag side of the same stack already excluded it. Apply the extension check used for backend tags (empty set accepts any extension), keeping loader_path null exactly when no loader can resolve the file. * fix(assets): refresh loader_path when re-ingesting an existing reference upsert_reference only wrote loader_path on the INSERT branch, so re-ingesting an existing reference (an output overwritten in place, or a file re-registered after its loader_path derivation changed) kept the stale or NULL value forever. Write it on the UPDATE branch too, with a null-safe change guard so a loader_path difference alone is enough to trigger the update, and identical values stay a no-op. * fix(assets): repair semantic merge breakage from #14796 and master Two textually-clean but semantically-broken merges: - routes.py lost its folder_paths import when #14796's import block superseded the base's, while the content-type hardening added via the base's master merge still calls folder_paths.is_dangerous_content_type. - master's SVG download-hardening test uploads with the pre-namespacing bare checkpoints tag, which this branch's destination validation rejects; use model_type:checkpoints. --------- Co-authored-by: guill <jacob.e.segal@gmail.com>
5101 lines
209 KiB
YAML
5101 lines
209 KiB
YAML
components:
|
|
schemas:
|
|
Asset:
|
|
description: Represents a user-owned asset (image, video, or other generated output).
|
|
properties:
|
|
created_at:
|
|
description: Timestamp when the asset was created
|
|
format: date-time
|
|
type: string
|
|
hash:
|
|
description: Blake3 hash of the asset content.
|
|
pattern: ^blake3:[a-f0-9]{64}$
|
|
type: string
|
|
loader_path:
|
|
description: The value a loader consumes to load this asset. Null when no loader can resolve the file.
|
|
nullable: true
|
|
type: string
|
|
display_name:
|
|
description: Human-facing label for the asset. Not unique.
|
|
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
|
|
short_url:
|
|
description: Durable, owner-gated short link to this asset's content (relative `/api/s/{id}` path). Stable across the underlying signed URL's expiry — resolving it re-mints a fresh signed URL on every request — so it is safe to persist or share into chat, unlike `preview_url`. Only the minting user can resolve it. Omitted when the short-link surface is disabled or the asset has no resolvable content hash.
|
|
nullable: true
|
|
type: string
|
|
x-runtime:
|
|
- cloud
|
|
size:
|
|
description: Size of the asset in bytes
|
|
format: int64
|
|
type: integer
|
|
tags:
|
|
description: Tags associated with the asset
|
|
items:
|
|
type: string
|
|
type: array
|
|
updated_at:
|
|
description: Timestamp when the asset was last updated
|
|
format: date-time
|
|
type: string
|
|
user_metadata:
|
|
additionalProperties: true
|
|
description: Custom user metadata for the asset
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
- created_at
|
|
- updated_at
|
|
type: object
|
|
AssetCreated:
|
|
allOf:
|
|
- $ref: '#/components/schemas/Asset'
|
|
- properties:
|
|
created_new:
|
|
description: Whether this was a new asset creation (true) or returned existing (false)
|
|
type: boolean
|
|
required:
|
|
- created_new
|
|
type: object
|
|
description: Response returned when a new asset is successfully created.
|
|
AssetInfo:
|
|
description: Lightweight asset reference used in workflow publishing payloads.
|
|
properties:
|
|
id:
|
|
description: Asset identifier.
|
|
type: string
|
|
in_library:
|
|
description: Whether the caller already owns this asset.
|
|
type: boolean
|
|
model:
|
|
description: Whether this asset is a model.
|
|
type: boolean
|
|
name:
|
|
type: string
|
|
preview_url:
|
|
description: Signed URL for previewing the asset.
|
|
type: string
|
|
public:
|
|
description: Whether this is a public (platform-provided) asset.
|
|
type: boolean
|
|
storage_url:
|
|
type: string
|
|
required:
|
|
- id
|
|
- name
|
|
- preview_url
|
|
- storage_url
|
|
- model
|
|
- public
|
|
- in_library
|
|
type: object
|
|
AssetTagHistogramResponse:
|
|
description: Histogram of tag counts used for refining asset search results.
|
|
properties:
|
|
tag_counts:
|
|
additionalProperties:
|
|
type: integer
|
|
description: Map of tag names to their occurrence counts on matching assets
|
|
example:
|
|
checkpoint: 32
|
|
lora: 193
|
|
vae: 6
|
|
type: object
|
|
required:
|
|
- tag_counts
|
|
type: object
|
|
AssetUpdated:
|
|
description: Response returned when an existing asset is successfully updated.
|
|
properties:
|
|
hash:
|
|
description: Blake3 hash of the asset content.
|
|
pattern: ^blake3:[a-f0-9]{64}$
|
|
type: string
|
|
id:
|
|
description: Asset ID
|
|
format: uuid
|
|
type: string
|
|
job_id:
|
|
description: ID of the job that created this asset, if available
|
|
format: uuid
|
|
nullable: true
|
|
type: string
|
|
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
|
|
CreateWorkflowRequest:
|
|
description: Request body for creating a new saved workflow.
|
|
properties:
|
|
default_view:
|
|
description: Default view mode
|
|
enum:
|
|
- workflow
|
|
- app
|
|
type: string
|
|
description:
|
|
description: Description of the workflow
|
|
type: string
|
|
forked_from_workflow_id:
|
|
description: ID of the source workflow if forked
|
|
type: string
|
|
forked_from_workflow_version_id:
|
|
description: ID of the source workflow version if forked
|
|
type: string
|
|
name:
|
|
description: Display name for the workflow
|
|
type: string
|
|
workflow_json:
|
|
additionalProperties: true
|
|
description: The ComfyUI workflow JSON
|
|
type: object
|
|
required:
|
|
- workflow_json
|
|
type: object
|
|
CreateWorkflowVersionRequest:
|
|
description: Request body for creating a new version of a saved workflow.
|
|
properties:
|
|
base_version:
|
|
description: The version number this change is based on (for optimistic concurrency)
|
|
type: integer
|
|
workflow_json:
|
|
additionalProperties: true
|
|
description: The updated ComfyUI workflow JSON
|
|
type: object
|
|
required:
|
|
- base_version
|
|
- workflow_json
|
|
type: object
|
|
ErrorResponse:
|
|
description: Standard error response with a machine-readable code and human-readable message.
|
|
properties:
|
|
code:
|
|
type: string
|
|
details:
|
|
additionalProperties: true
|
|
description: Optional open object carrying structured, machine-readable context about the error (e.g. offending field names, validation specifics). Absent for most errors; consumers must not assume any particular shape.
|
|
type: object
|
|
message:
|
|
type: string
|
|
required:
|
|
- code
|
|
- message
|
|
type: object
|
|
ExecutionError:
|
|
description: Detailed execution error information from ComfyUI
|
|
properties:
|
|
current_inputs:
|
|
additionalProperties: true
|
|
description: Input values at time of failure (empty object if not available)
|
|
type: object
|
|
current_outputs:
|
|
additionalProperties: true
|
|
description: Output values at time of failure (empty object if not available)
|
|
type: object
|
|
exception_message:
|
|
description: Human-readable error message
|
|
type: string
|
|
exception_type:
|
|
description: Python exception type (e.g., "RuntimeError")
|
|
type: string
|
|
node_id:
|
|
description: ID of the node that failed
|
|
type: string
|
|
node_type:
|
|
description: Type name of the node (e.g., "KSampler")
|
|
type: string
|
|
traceback:
|
|
description: Array of traceback lines (empty array if not available)
|
|
items:
|
|
type: string
|
|
type: array
|
|
required:
|
|
- node_id
|
|
- node_type
|
|
- exception_message
|
|
- exception_type
|
|
- traceback
|
|
- current_inputs
|
|
- current_outputs
|
|
type: object
|
|
FeedbackRequest:
|
|
description: Request to submit user feedback
|
|
properties:
|
|
content:
|
|
description: The feedback content or message
|
|
type: string
|
|
metadata:
|
|
additionalProperties: true
|
|
description: Additional metadata about the feedback
|
|
type: object
|
|
rating:
|
|
description: User's rating of ComfyUI Cloud experience (1-5 stars)
|
|
maximum: 5
|
|
minimum: 1
|
|
type: integer
|
|
type:
|
|
description: Type of feedback being submitted
|
|
enum:
|
|
- missing_nodes
|
|
- general
|
|
- missing_models
|
|
type: string
|
|
required:
|
|
- type
|
|
type: object
|
|
FeedbackResponse:
|
|
description: Response after submitting feedback
|
|
type: object
|
|
ForkWorkflowRequest:
|
|
description: Request body for forking an existing workflow into the user's account.
|
|
properties:
|
|
name:
|
|
description: Name for the forked workflow
|
|
type: string
|
|
source_version:
|
|
description: Version number to fork from
|
|
type: integer
|
|
required:
|
|
- source_version
|
|
type: object
|
|
GetUserDataResponseFull:
|
|
description: List of user data file entries (each with path, size, and modification time) returned when full_info=true.
|
|
items:
|
|
$ref: '#/components/schemas/GetUserDataResponseFullFile'
|
|
type: array
|
|
GetUserDataResponseFullFile:
|
|
description: Individual file entry within a full user data response.
|
|
properties:
|
|
modified:
|
|
description: UNIX timestamp of the last modification in milliseconds.
|
|
format: int64
|
|
type: integer
|
|
path:
|
|
description: File name or path relative to the user directory.
|
|
type: string
|
|
size:
|
|
description: File size in bytes.
|
|
type: integer
|
|
type: object
|
|
GlobalSubgraphData:
|
|
description: Full data for a global subgraph blueprint
|
|
properties:
|
|
data:
|
|
description: The full subgraph JSON data as a string
|
|
type: string
|
|
info:
|
|
description: Additional information about the subgraph
|
|
properties:
|
|
node_pack:
|
|
description: The node pack/module that provides this subgraph
|
|
type: string
|
|
required:
|
|
- node_pack
|
|
type: object
|
|
name:
|
|
description: Display name of the subgraph blueprint
|
|
type: string
|
|
source:
|
|
description: Source type of the subgraph - "templates" for workflow templates or "custom_node" for custom node subgraphs
|
|
type: string
|
|
required:
|
|
- source
|
|
- name
|
|
- info
|
|
- data
|
|
type: object
|
|
GlobalSubgraphInfo:
|
|
description: Metadata for a global subgraph blueprint (without full data)
|
|
properties:
|
|
data:
|
|
description: The full subgraph JSON data (may be empty in list view)
|
|
type: string
|
|
info:
|
|
description: Additional information about the subgraph
|
|
properties:
|
|
node_pack:
|
|
description: The node pack/module that provides this subgraph
|
|
type: string
|
|
required:
|
|
- node_pack
|
|
type: object
|
|
name:
|
|
description: Display name of the subgraph blueprint
|
|
type: string
|
|
source:
|
|
description: Source type of the subgraph - "templates" for workflow templates or "custom_node" for custom node subgraphs
|
|
type: string
|
|
required:
|
|
- source
|
|
- name
|
|
- info
|
|
type: object
|
|
HistoryDetailEntry:
|
|
description: History entry with full prompt data
|
|
properties:
|
|
meta:
|
|
additionalProperties: true
|
|
description: Metadata about the execution and nodes
|
|
type: object
|
|
outputs:
|
|
additionalProperties: true
|
|
description: Output data from execution (generated images, files, etc.)
|
|
type: object
|
|
prompt:
|
|
description: Full prompt execution data
|
|
properties:
|
|
extra_data:
|
|
additionalProperties: true
|
|
description: Additional execution data
|
|
type: object
|
|
outputs_to_execute:
|
|
description: Output nodes to execute
|
|
items:
|
|
type: string
|
|
type: array
|
|
priority:
|
|
description: Execution priority
|
|
format: double
|
|
type: number
|
|
prompt:
|
|
additionalProperties: true
|
|
description: The workflow nodes
|
|
type: object
|
|
prompt_id:
|
|
description: The prompt ID
|
|
type: string
|
|
type: object
|
|
status:
|
|
additionalProperties: true
|
|
description: Execution status and timeline information
|
|
type: object
|
|
type: object
|
|
HistoryDetailResponse:
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/HistoryDetailEntry'
|
|
description: |
|
|
Detailed execution history response for a specific prompt.
|
|
Returns a dictionary with prompt_id as key and full history data as value.
|
|
type: object
|
|
HistoryEntry:
|
|
description: History entry with prompt_id and execution data
|
|
properties:
|
|
create_time:
|
|
description: Job creation timestamp (Unix timestamp in milliseconds)
|
|
format: int64
|
|
type: integer
|
|
meta:
|
|
additionalProperties: true
|
|
description: Metadata about the execution and nodes
|
|
type: object
|
|
outputs:
|
|
additionalProperties: true
|
|
description: Output data from execution (generated images, files, etc.)
|
|
type: object
|
|
prompt:
|
|
description: Filtered prompt execution data (lightweight format)
|
|
properties:
|
|
extra_data:
|
|
additionalProperties: true
|
|
description: Additional execution data (workflow removed from extra_pnginfo)
|
|
type: object
|
|
priority:
|
|
description: Execution priority
|
|
format: double
|
|
type: number
|
|
prompt_id:
|
|
description: The prompt ID
|
|
type: string
|
|
type: object
|
|
prompt_id:
|
|
description: Unique identifier for this prompt execution
|
|
type: string
|
|
status:
|
|
additionalProperties: true
|
|
description: Execution status and timeline information
|
|
type: object
|
|
workflow_id:
|
|
description: UUID identifying the workflow graph definition
|
|
type: string
|
|
required:
|
|
- prompt_id
|
|
type: object
|
|
HistoryManageRequest:
|
|
additionalProperties: false
|
|
description: Request to manage history operations
|
|
properties:
|
|
clear:
|
|
description: If true, clear all history for the authenticated user
|
|
type: boolean
|
|
delete:
|
|
description: Array of job IDs to delete from history
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
HistoryResponse:
|
|
description: |
|
|
Execution history response with history array.
|
|
Returns an object with a "history" key containing an array of history entries.
|
|
Each entry includes prompt_id as a property along with execution data.
|
|
properties:
|
|
history:
|
|
description: Array of history entries ordered by creation time (newest first)
|
|
items:
|
|
$ref: '#/components/schemas/HistoryEntry'
|
|
type: array
|
|
required:
|
|
- history
|
|
type: object
|
|
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
|
|
JobsCancelRequest:
|
|
additionalProperties: false
|
|
description: Request to cancel multiple jobs by ID.
|
|
properties:
|
|
job_ids:
|
|
description: Job identifiers (UUIDs) to cancel.
|
|
items:
|
|
format: uuid
|
|
type: string
|
|
maxItems: 100
|
|
minItems: 1
|
|
type: array
|
|
required:
|
|
- job_ids
|
|
type: object
|
|
JobsCancelResponse:
|
|
description: Response for POST /api/jobs/cancel.
|
|
properties:
|
|
cancelled:
|
|
description: |
|
|
Job IDs for which a cancel event was successfully dispatched by this
|
|
call. Jobs already in a terminal or cancelling state are idempotently
|
|
skipped and will not appear here.
|
|
items:
|
|
type: string
|
|
type: array
|
|
required:
|
|
- cancelled
|
|
type: object
|
|
JobsListResponse:
|
|
description: Paginated list of jobs for the authenticated user.
|
|
properties:
|
|
jobs:
|
|
description: Array of jobs ordered by specified sort field
|
|
items:
|
|
$ref: '#/components/schemas/JobEntry'
|
|
type: array
|
|
pagination:
|
|
$ref: '#/components/schemas/PaginationInfo'
|
|
required:
|
|
- jobs
|
|
- pagination
|
|
type: object
|
|
ListAssetsResponse:
|
|
description: Paginated list of assets belonging to the authenticated user.
|
|
properties:
|
|
assets:
|
|
description: List of assets matching the query
|
|
items:
|
|
$ref: '#/components/schemas/Asset'
|
|
type: array
|
|
has_more:
|
|
description: Whether more assets are available beyond this page
|
|
type: boolean
|
|
next_cursor:
|
|
description: |
|
|
Opaque cursor to pass as the `after` query parameter to fetch the
|
|
next page. Omitted from the response when there are no more results.
|
|
type: string
|
|
total:
|
|
description: Total number of assets matching the filters
|
|
type: integer
|
|
required:
|
|
- assets
|
|
- total
|
|
- has_more
|
|
type: object
|
|
ListTagsResponse:
|
|
description: Paginated list of available asset tags.
|
|
properties:
|
|
has_more:
|
|
description: Whether more tags are available
|
|
type: boolean
|
|
tags:
|
|
description: List of tags
|
|
items:
|
|
$ref: '#/components/schemas/TagInfo'
|
|
type: array
|
|
total:
|
|
description: Total number of tags
|
|
type: integer
|
|
required:
|
|
- tags
|
|
- total
|
|
- has_more
|
|
type: object
|
|
ModelFile:
|
|
description: Represents a model file with metadata
|
|
properties:
|
|
name:
|
|
description: The filename of the model
|
|
example: model.safetensors
|
|
type: string
|
|
pathIndex:
|
|
description: Index of the path where this model is located
|
|
example: 0
|
|
type: integer
|
|
required:
|
|
- name
|
|
- pathIndex
|
|
type: object
|
|
ModelFolder:
|
|
description: Represents a folder containing models
|
|
properties:
|
|
folders:
|
|
description: List of paths where models of this type are stored
|
|
example:
|
|
- checkpoints
|
|
items:
|
|
type: string
|
|
type: array
|
|
name:
|
|
description: The name of the model folder
|
|
example: checkpoints
|
|
type: string
|
|
required:
|
|
- name
|
|
- folders
|
|
type: object
|
|
NodeInfo:
|
|
description: Metadata describing a single ComfyUI node type and its inputs/outputs.
|
|
properties:
|
|
api_node:
|
|
description: Whether this is an API node
|
|
type: boolean
|
|
category:
|
|
description: Category of the node
|
|
type: string
|
|
deprecated:
|
|
description: Whether the node is deprecated
|
|
type: boolean
|
|
description:
|
|
description: Description of the node
|
|
type: string
|
|
display_name:
|
|
description: Display name of the node
|
|
type: string
|
|
experimental:
|
|
description: Whether the node is experimental
|
|
type: boolean
|
|
input:
|
|
additionalProperties: true
|
|
description: Input specifications for the node
|
|
type: object
|
|
input_order:
|
|
additionalProperties:
|
|
items:
|
|
type: string
|
|
type: array
|
|
description: Order of inputs for display
|
|
type: object
|
|
name:
|
|
description: Internal name of the node
|
|
type: string
|
|
output:
|
|
description: Output types of the node
|
|
items:
|
|
type: string
|
|
type: array
|
|
output_is_list:
|
|
description: Whether each output is a list
|
|
items:
|
|
type: boolean
|
|
type: array
|
|
output_name:
|
|
description: Names of the outputs
|
|
items:
|
|
type: string
|
|
type: array
|
|
output_node:
|
|
description: Whether this is an output node
|
|
type: boolean
|
|
output_tooltips:
|
|
description: Tooltips for outputs
|
|
items:
|
|
type: string
|
|
type: array
|
|
python_module:
|
|
description: Python module implementing the node
|
|
type: string
|
|
type: object
|
|
PaginationInfo:
|
|
description: |
|
|
Pagination metadata included in list responses. Supports both legacy
|
|
offset/limit pagination and cursor-based pagination. When cursor-based
|
|
pagination is used, `next_cursor` is the primary pagination token and
|
|
`offset`/`total` may be zero.
|
|
properties:
|
|
has_more:
|
|
description: Whether more items are available beyond this page
|
|
type: boolean
|
|
limit:
|
|
description: Items per page
|
|
minimum: 1
|
|
type: integer
|
|
next_cursor:
|
|
description: |
|
|
Opaque cursor for the next page. Pass this value as the `after`
|
|
query parameter on the next request. Empty or absent when there
|
|
are no more results.
|
|
type: string
|
|
offset:
|
|
deprecated: true
|
|
description: 'Current offset (0-based). Deprecated: use cursor-based pagination.'
|
|
minimum: 0
|
|
type: integer
|
|
total:
|
|
description: Total number of items matching filters (may be 0 when using cursor pagination)
|
|
minimum: 0
|
|
type: integer
|
|
required:
|
|
- offset
|
|
- limit
|
|
- total
|
|
- has_more
|
|
type: object
|
|
PromptErrorResponse:
|
|
additionalProperties: true
|
|
description: Error response for ComfyUI prompt execution.
|
|
type: object
|
|
PromptInfo:
|
|
description: Metadata about the currently running and queued prompts.
|
|
properties:
|
|
exec_info:
|
|
properties:
|
|
queue_remaining:
|
|
description: Number of items remaining in the queue
|
|
type: integer
|
|
type: object
|
|
type: object
|
|
PromptRequest:
|
|
description: Request body for submitting a ComfyUI workflow prompt for execution.
|
|
properties:
|
|
extra_data:
|
|
additionalProperties: true
|
|
description: Extra data to be associated with the prompt
|
|
type: object
|
|
front:
|
|
description: If true, adds the prompt to the front of the queue
|
|
type: boolean
|
|
number:
|
|
description: Priority number for the queue (lower numbers have higher priority)
|
|
type: number
|
|
partial_execution_targets:
|
|
description: List of node names to execute
|
|
items:
|
|
type: string
|
|
type: array
|
|
prompt:
|
|
additionalProperties: true
|
|
description: The workflow graph to execute
|
|
type: object
|
|
workflow_id:
|
|
description: UUID identifying the cloud workflow entity to associate with this job
|
|
type: string
|
|
workflow_version_id:
|
|
description: UUID identifying the workflow version to associate with this job
|
|
type: string
|
|
required:
|
|
- prompt
|
|
type: object
|
|
PromptResponse:
|
|
description: Response returned after successfully queuing a workflow prompt.
|
|
properties:
|
|
node_errors:
|
|
additionalProperties: true
|
|
description: Any errors in the nodes of the prompt
|
|
type: object
|
|
number:
|
|
description: Priority number in the queue
|
|
type: number
|
|
prompt_id:
|
|
description: Unique identifier for the prompt execution
|
|
format: uuid
|
|
type: string
|
|
type: object
|
|
PublishWorkflowAssetsRequest:
|
|
description: Request body for publishing workflow assets to the Hub.
|
|
properties:
|
|
asset_ids:
|
|
description: IDs of assets (inputs and models) to snapshot.
|
|
items:
|
|
type: string
|
|
type: array
|
|
required:
|
|
- asset_ids
|
|
type: object
|
|
PublishedWorkflowDetail:
|
|
description: Full detail of a publicly published workflow on the Hub.
|
|
properties:
|
|
assets:
|
|
description: Published assets with their library status for the caller.
|
|
items:
|
|
$ref: '#/components/schemas/AssetInfo'
|
|
type: array
|
|
listed:
|
|
type: boolean
|
|
name:
|
|
description: Human-readable workflow name.
|
|
type: string
|
|
publish_time:
|
|
format: date-time
|
|
nullable: true
|
|
type: string
|
|
share_id:
|
|
type: string
|
|
workflow_id:
|
|
type: string
|
|
workflow_json:
|
|
additionalProperties: true
|
|
description: The workflow JSON content at publish time.
|
|
type: object
|
|
required:
|
|
- share_id
|
|
- workflow_id
|
|
- name
|
|
- listed
|
|
- workflow_json
|
|
- assets
|
|
type: object
|
|
QueueInfo:
|
|
description: Queue information with pending and running jobs
|
|
properties:
|
|
queue_pending:
|
|
description: Array of pending job items (ordered by creation time, oldest first)
|
|
items:
|
|
description: |
|
|
Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata]
|
|
- [0] job_number (integer): Position in queue (1-based)
|
|
- [1] prompt_id (string): Job UUID
|
|
- [2] workflow_json (object): Full ComfyUI workflow
|
|
- [3] output_node_ids (array): Node IDs to return results from
|
|
- [4] metadata (object): Contains {create_time: <milliseconds>}
|
|
items: {}
|
|
maxItems: 5
|
|
minItems: 5
|
|
type: array
|
|
type: array
|
|
queue_running:
|
|
description: Array of currently running job items
|
|
items:
|
|
description: |
|
|
Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata]
|
|
- [0] job_number (integer): Position in queue (1-based)
|
|
- [1] prompt_id (string): Job UUID
|
|
- [2] workflow_json (object): Full ComfyUI workflow
|
|
- [3] output_node_ids (array): Node IDs to return results from
|
|
- [4] metadata (object): Contains {create_time: <milliseconds>}
|
|
items: {}
|
|
maxItems: 5
|
|
minItems: 5
|
|
type: array
|
|
type: array
|
|
type: object
|
|
QueueManageRequest:
|
|
additionalProperties: false
|
|
description: Request to manage queue operations
|
|
properties:
|
|
clear:
|
|
description: If true, clear all pending jobs from the queue
|
|
type: boolean
|
|
delete:
|
|
description: Array of job IDs to cancel; pending and running jobs transition to cancelled
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
QueueManageResponse:
|
|
description: Response after a queue management action (delete or clear).
|
|
properties:
|
|
cleared:
|
|
description: Whether the queue was cleared
|
|
type: boolean
|
|
deleted:
|
|
description: Array of job IDs that were successfully cancelled
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
SystemStatsResponse:
|
|
description: System statistics response
|
|
properties:
|
|
devices:
|
|
items:
|
|
properties:
|
|
name:
|
|
description: Device name
|
|
type: string
|
|
type:
|
|
description: Device type
|
|
type: string
|
|
vram_free:
|
|
description: Free VRAM in bytes
|
|
type: number
|
|
vram_total:
|
|
description: Total VRAM in bytes
|
|
type: number
|
|
required:
|
|
- name
|
|
- type
|
|
type: object
|
|
type: array
|
|
system:
|
|
properties:
|
|
argv:
|
|
description: Command line arguments
|
|
items:
|
|
type: string
|
|
type: array
|
|
cloud_version:
|
|
description: Cloud ingest service version (commit hash)
|
|
type: string
|
|
comfyui_frontend_version:
|
|
description: ComfyUI frontend version (commit hash or tag)
|
|
type: string
|
|
comfyui_version:
|
|
description: ComfyUI version
|
|
type: string
|
|
deploy_environment:
|
|
description: How this ComfyUI instance is deployed (e.g. cloud, local-git, local-portable, local-desktop)
|
|
type: string
|
|
embedded_python:
|
|
description: Whether using embedded Python
|
|
type: boolean
|
|
os:
|
|
description: Operating system
|
|
type: string
|
|
python_version:
|
|
description: Python version
|
|
type: string
|
|
pytorch_version:
|
|
description: PyTorch version
|
|
type: string
|
|
ram_free:
|
|
description: Free RAM in bytes
|
|
type: number
|
|
ram_total:
|
|
description: Total RAM in bytes
|
|
type: number
|
|
workflow_templates_version:
|
|
description: Workflow templates version
|
|
type: string
|
|
required:
|
|
- os
|
|
- python_version
|
|
- embedded_python
|
|
- comfyui_version
|
|
- pytorch_version
|
|
- argv
|
|
- ram_total
|
|
- ram_free
|
|
type: object
|
|
required:
|
|
- system
|
|
- devices
|
|
type: object
|
|
TagInfo:
|
|
description: Metadata for a single tag that can be applied to assets.
|
|
properties:
|
|
count:
|
|
description: Number of assets using this tag
|
|
type: integer
|
|
name:
|
|
description: Tag name
|
|
type: string
|
|
required:
|
|
- name
|
|
- count
|
|
type: object
|
|
TagsModificationResponse:
|
|
description: Response after adding, updating, or removing tags on an asset.
|
|
properties:
|
|
added:
|
|
description: Tags that were successfully added (for add operation)
|
|
items:
|
|
type: string
|
|
type: array
|
|
already_present:
|
|
description: Tags that were already present (for add operation)
|
|
items:
|
|
type: string
|
|
type: array
|
|
not_present:
|
|
description: Tags that were not present (for remove operation)
|
|
items:
|
|
type: string
|
|
type: array
|
|
removed:
|
|
description: Tags that were successfully removed (for remove operation)
|
|
items:
|
|
type: string
|
|
type: array
|
|
total_tags:
|
|
description: All tags on the asset after the operation
|
|
items:
|
|
type: string
|
|
type: array
|
|
required:
|
|
- total_tags
|
|
type: object
|
|
TaskEntry:
|
|
description: Task data for list views
|
|
properties:
|
|
completed_at:
|
|
description: When task completed or failed (null if not finished)
|
|
format: date-time
|
|
type: string
|
|
create_time:
|
|
description: Task creation timestamp
|
|
format: date-time
|
|
type: string
|
|
id:
|
|
description: Unique task identifier
|
|
format: uuid
|
|
type: string
|
|
started_at:
|
|
description: When task execution started (null if not started)
|
|
format: date-time
|
|
type: string
|
|
status:
|
|
description: Current task status
|
|
enum:
|
|
- created
|
|
- running
|
|
- completed
|
|
- failed
|
|
type: string
|
|
task_name:
|
|
description: Task type name (e.g., model_upload)
|
|
type: string
|
|
required:
|
|
- id
|
|
- task_name
|
|
- status
|
|
- create_time
|
|
type: object
|
|
TaskResponse:
|
|
description: Full task details including payload and result
|
|
properties:
|
|
completed_at:
|
|
description: When task completed or failed (null if not finished)
|
|
format: date-time
|
|
type: string
|
|
create_time:
|
|
description: Task creation timestamp
|
|
format: date-time
|
|
type: string
|
|
error_message:
|
|
description: Error message on failure (null if not failed)
|
|
type: string
|
|
id:
|
|
description: Unique task identifier
|
|
format: uuid
|
|
type: string
|
|
idempotency_key:
|
|
description: Caller-provided key for idempotent task creation
|
|
type: string
|
|
payload:
|
|
additionalProperties: true
|
|
description: Task input data
|
|
type: object
|
|
result:
|
|
additionalProperties: true
|
|
description: Task output data (null if not completed)
|
|
type: object
|
|
started_at:
|
|
description: When task execution started (null if not started)
|
|
format: date-time
|
|
type: string
|
|
status:
|
|
description: Current task status
|
|
enum:
|
|
- created
|
|
- running
|
|
- completed
|
|
- failed
|
|
type: string
|
|
task_name:
|
|
description: Task type name (e.g., model_upload)
|
|
type: string
|
|
update_time:
|
|
description: Task last update timestamp
|
|
format: date-time
|
|
type: string
|
|
required:
|
|
- id
|
|
- idempotency_key
|
|
- task_name
|
|
- payload
|
|
- status
|
|
- create_time
|
|
- update_time
|
|
type: object
|
|
TasksListResponse:
|
|
description: Paginated list of background tasks for the authenticated user.
|
|
properties:
|
|
pagination:
|
|
$ref: '#/components/schemas/PaginationInfo'
|
|
tasks:
|
|
description: Array of tasks ordered by create_time
|
|
items:
|
|
$ref: '#/components/schemas/TaskEntry'
|
|
type: array
|
|
required:
|
|
- tasks
|
|
- pagination
|
|
type: object
|
|
UpdateWorkflowRequest:
|
|
description: Request body for updating an existing saved workflow.
|
|
properties:
|
|
default_view:
|
|
description: New default view mode
|
|
enum:
|
|
- workflow
|
|
- app
|
|
type: string
|
|
description:
|
|
description: New description
|
|
type: string
|
|
name:
|
|
description: New display name
|
|
type: string
|
|
type: object
|
|
UserDataResponseFull:
|
|
description: User data listing entry with file metadata (path, size, modification time).
|
|
properties:
|
|
modified:
|
|
description: UNIX timestamp of the last modification in milliseconds.
|
|
format: int64
|
|
type: integer
|
|
path:
|
|
type: string
|
|
size:
|
|
type: integer
|
|
type: object
|
|
UserResponse:
|
|
description: User information response
|
|
properties:
|
|
id:
|
|
description: Firebase UID of the authenticated user
|
|
type: string
|
|
status:
|
|
description: User status (always "active" for authenticated users)
|
|
type: string
|
|
required:
|
|
- id
|
|
- status
|
|
type: object
|
|
WorkflowForkedFrom:
|
|
description: Reference to the parent workflow from which this workflow was forked.
|
|
properties:
|
|
workflow_id:
|
|
type: string
|
|
workflow_version_id:
|
|
type: string
|
|
type: object
|
|
WorkflowListResponse:
|
|
description: Paginated list of saved workflows.
|
|
properties:
|
|
data:
|
|
items:
|
|
$ref: '#/components/schemas/WorkflowResponse'
|
|
type: array
|
|
pagination:
|
|
$ref: '#/components/schemas/PaginationInfo'
|
|
required:
|
|
- data
|
|
- pagination
|
|
type: object
|
|
WorkflowPublishInfo:
|
|
description: Publishing metadata for a workflow shared to the Hub.
|
|
properties:
|
|
assets:
|
|
description: Published assets (inputs and models).
|
|
items:
|
|
$ref: '#/components/schemas/AssetInfo'
|
|
type: array
|
|
listed:
|
|
type: boolean
|
|
publish_time:
|
|
format: date-time
|
|
nullable: true
|
|
type: string
|
|
share_id:
|
|
type: string
|
|
workflow_id:
|
|
type: string
|
|
required:
|
|
- workflow_id
|
|
- share_id
|
|
- listed
|
|
- assets
|
|
type: object
|
|
WorkflowResponse:
|
|
description: Full workflow entity including metadata and version history.
|
|
properties:
|
|
created_at:
|
|
format: date-time
|
|
type: string
|
|
created_by:
|
|
type: string
|
|
default_view:
|
|
enum:
|
|
- workflow
|
|
- app
|
|
type: string
|
|
description:
|
|
type: string
|
|
forked_from:
|
|
$ref: '#/components/schemas/WorkflowForkedFrom'
|
|
id:
|
|
type: string
|
|
latest_version:
|
|
type: integer
|
|
name:
|
|
type: string
|
|
updated_at:
|
|
format: date-time
|
|
type: string
|
|
required:
|
|
- id
|
|
- latest_version
|
|
- created_by
|
|
- created_at
|
|
- updated_at
|
|
type: object
|
|
WorkflowVersionContentResponse:
|
|
description: Full workflow version including the serialized workflow JSON.
|
|
properties:
|
|
created_at:
|
|
format: date-time
|
|
type: string
|
|
created_by:
|
|
type: string
|
|
dependency_asset_ids:
|
|
items:
|
|
type: string
|
|
type: array
|
|
id:
|
|
type: string
|
|
version:
|
|
type: integer
|
|
workflow_json:
|
|
additionalProperties: true
|
|
type: object
|
|
required:
|
|
- id
|
|
- version
|
|
- workflow_json
|
|
- created_by
|
|
- created_at
|
|
type: object
|
|
WorkflowVersionResponse:
|
|
description: Metadata for a single workflow version.
|
|
properties:
|
|
created_at:
|
|
format: date-time
|
|
type: string
|
|
created_by:
|
|
type: string
|
|
id:
|
|
type: string
|
|
latest_version:
|
|
type: integer
|
|
version:
|
|
type: integer
|
|
required:
|
|
- id
|
|
- version
|
|
- latest_version
|
|
- created_by
|
|
- created_at
|
|
type: object
|
|
securitySchemes:
|
|
ApiKeyAuth:
|
|
description: |
|
|
API key authentication. Keys are prefixed with 'comfyui-' and can be
|
|
generated from user account settings. Example: 'comfyui-abc123...'
|
|
in: header
|
|
name: X-API-Key
|
|
type: apiKey
|
|
BearerAuth:
|
|
bearerFormat: JWT
|
|
description: |
|
|
Firebase JWT token authentication. Obtain a token by authenticating
|
|
with Firebase and pass it in the Authorization header.
|
|
scheme: bearer
|
|
type: http
|
|
CookieAuth:
|
|
description: |
|
|
Session cookie authentication. Set automatically after successful
|
|
login via the /api/auth/session endpoint.
|
|
in: cookie
|
|
name: session
|
|
type: apiKey
|
|
info:
|
|
description: |
|
|
API for ComfyUI - A powerful and modular UI for Stable Diffusion.
|
|
|
|
This API allows you to interact with ComfyUI programmatically, including:
|
|
- Retrieving prompt information
|
|
- Retrieving node information
|
|
license:
|
|
name: GNU General Public License v3.0
|
|
url: https://github.com/Comfy-Org/ComfyUI/blob/master/LICENSE
|
|
title: ComfyUI API
|
|
version: 1.0.0
|
|
openapi: 3.0.3
|
|
paths:
|
|
/api/assets:
|
|
get:
|
|
description: |
|
|
Retrieves a paginated list of assets belonging to the authenticated user.
|
|
Supports filtering by tags, name, metadata, and sorting options.
|
|
operationId: listAssets
|
|
parameters:
|
|
- 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: hash
|
|
schema:
|
|
type: string
|
|
- description: |
|
|
Opaque cursor for keyset pagination. Pass the `next_cursor` value
|
|
from the previous response to fetch the next page. When provided,
|
|
`offset` is ignored. Cursor pagination is only supported with
|
|
`sort` values `created_at`, `updated_at`, `name`, or `size`;
|
|
requests combining `after` with other sort fields return 400.
|
|
The cursor must have been minted under the same `sort` value used
|
|
in the follow-up request.
|
|
in: query
|
|
name: after
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ListAssetsResponse'
|
|
description: Success - Assets returned
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: List user assets
|
|
tags:
|
|
- file
|
|
post:
|
|
description: |
|
|
Creates a new asset from a direct file upload (multipart/form-data) with associated metadata.
|
|
|
|
If an asset with the same hash already exists, returns the existing asset.
|
|
operationId: createAsset
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
properties:
|
|
file:
|
|
description: The asset file to upload
|
|
format: binary
|
|
type: string
|
|
hash:
|
|
description: Content hash of the file.
|
|
pattern: ^(blake3|sha256):[a-f0-9]{64}$
|
|
type: string
|
|
id:
|
|
description: Optional asset ID for idempotent creation. If provided and asset exists, returns existing asset.
|
|
format: uuid
|
|
type: string
|
|
mime_type:
|
|
description: MIME type of the asset (e.g., "image/png", "video/mp4")
|
|
type: string
|
|
name:
|
|
description: Display name for the asset
|
|
type: string
|
|
preview_id:
|
|
description: Optional preview asset ID. If not provided, images will use their own ID as preview.
|
|
format: uuid
|
|
type: string
|
|
tags:
|
|
description: JSON-encoded array of tag strings. For new byte uploads, include exactly one destination role (`input`, `output`, or `models`); `models` uploads also require exactly one `model_type:<folder_name>` tag. Extra tags are stored as labels and do not create path components.
|
|
type: string
|
|
user_metadata:
|
|
description: Custom JSON metadata as a string
|
|
type: string
|
|
required:
|
|
- file
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetCreated'
|
|
description: |
|
|
Asset already existed for this user (deduplicated by content hash); the
|
|
existing asset is returned with created_new=false.
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetCreated'
|
|
description: Asset created successfully (created_new=true)
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request (bad file, invalid content type, etc.)
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"413":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: File too large
|
|
"415":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unsupported media type
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error (e.g., disallowed model_type tag)
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Create a new asset
|
|
tags:
|
|
- file
|
|
/api/assets/{id}:
|
|
delete:
|
|
description: Deletes the asset record.
|
|
operationId: deleteAsset
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"204":
|
|
description: Asset record deleted successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Asset not found
|
|
"409":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: 'Asset cannot be deleted because it is referenced by another resource, e.g. a workflow version (error code: ASSET_IN_USE)'
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Delete asset
|
|
tags:
|
|
- file
|
|
get:
|
|
description: Retrieves detailed information about a specific asset
|
|
operationId: getAssetById
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Asset'
|
|
description: Asset details retrieved successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Asset not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get asset details
|
|
tags:
|
|
- file
|
|
put:
|
|
description: |
|
|
Updates an asset's metadata. At least one field must be provided.
|
|
Only name, mime_type, preview_id, and user_metadata can be updated.
|
|
For tag management, use POST (add) and DELETE (remove) /api/assets/{id}/tags.
|
|
operationId: updateAsset
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
minProperties: 1
|
|
properties:
|
|
mime_type:
|
|
description: Updated MIME type of the asset
|
|
type: string
|
|
name:
|
|
description: New display name for the asset
|
|
type: string
|
|
preview_id:
|
|
description: Updated preview asset ID
|
|
format: uuid
|
|
type: string
|
|
user_metadata:
|
|
additionalProperties: true
|
|
description: Updated custom metadata
|
|
type: object
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/Asset'
|
|
description: Asset updated successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: |
|
|
Invalid request — no fields provided, or `preview_id` is the zero UUID
|
|
(`INVALID_PREVIEW_ID`).
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: |
|
|
Asset not found — returned both when the asset being updated does
|
|
not exist and when `preview_id` does not reference an asset
|
|
accessible to the caller.
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Update asset metadata
|
|
tags:
|
|
- file
|
|
/api/assets/{id}/content:
|
|
get:
|
|
description: |
|
|
Returns the binary content of an asset by ID.
|
|
|
|
The contract is the same across runtimes — "GET this path and you
|
|
receive the asset's bytes" — but the mechanism differs:
|
|
- **Local ComfyUI** streams the bytes directly (`200`,
|
|
`application/octet-stream`).
|
|
- **Cloud** does not proxy large files; it responds `302` with a
|
|
`Location` redirect to a short-lived signed storage URL. Clients that
|
|
follow redirects (browsers, `fetch`/XHR, `<img>`/`<video>`) receive
|
|
the bytes transparently.
|
|
|
|
Prefer this over the filename-addressed `/api/view` when you have an
|
|
asset ID.
|
|
operationId: getAssetContent
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- description: |
|
|
Content-Disposition for the response: `attachment` (download) or
|
|
`inline` (render in browser). Defaults to `attachment`.
|
|
in: query
|
|
name: disposition
|
|
schema:
|
|
default: attachment
|
|
enum:
|
|
- inline
|
|
- attachment
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
format: binary
|
|
type: string
|
|
description: Asset content stream (local runtime streams the bytes directly)
|
|
"302":
|
|
description: Redirect to a signed storage URL (cloud runtime)
|
|
headers:
|
|
Cache-Control:
|
|
description: Private caching directive scoped to the signed URL lifetime
|
|
schema:
|
|
type: string
|
|
Location:
|
|
description: Short-lived signed URL to the asset content in storage
|
|
schema:
|
|
type: string
|
|
Vary:
|
|
description: Partitions any cached redirect by auth credentials so a private redirect is not reused across users
|
|
schema:
|
|
type: string
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Asset not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
- CookieAuth: []
|
|
summary: Get asset content
|
|
tags:
|
|
- file
|
|
/api/assets/{id}/tags:
|
|
delete:
|
|
description: Removes one or more tags from an existing asset
|
|
operationId: removeAssetTags
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
tags:
|
|
description: Tags to remove from the asset
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
type: array
|
|
required:
|
|
- tags
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TagsModificationResponse'
|
|
description: Tags removed successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Asset not found
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error (e.g., reserved tag)
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Remove tags from asset
|
|
tags:
|
|
- file
|
|
post:
|
|
description: Adds one or more tags to an existing asset
|
|
operationId: addAssetTags
|
|
parameters:
|
|
- description: Asset ID
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
tags:
|
|
description: Tags to add to the asset
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
type: array
|
|
required:
|
|
- tags
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TagsModificationResponse'
|
|
description: Tags added successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Asset not found
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error (e.g., reserved tag)
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Add tags to asset
|
|
tags:
|
|
- file
|
|
/api/assets/from-hash:
|
|
post:
|
|
description: |
|
|
Creates a new asset reference using an existing asset's hash.
|
|
This avoids re-uploading the file content when the asset already exists in storage.
|
|
The user can provide their own metadata and tags for the reference.
|
|
operationId: createAssetFromHash
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
hash:
|
|
description: 'Blake3 content hash of the existing asset (blake3: prefix)'
|
|
pattern: ^blake3:[a-f0-9]{64}$
|
|
type: string
|
|
mime_type:
|
|
description: MIME type of the asset (e.g., "image/png", "video/mp4")
|
|
type: string
|
|
name:
|
|
description: Display name for the asset reference (optional)
|
|
type: string
|
|
tags:
|
|
description: Freeform tags for the asset. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.
|
|
items:
|
|
type: string
|
|
minItems: 1
|
|
type: array
|
|
user_metadata:
|
|
additionalProperties: true
|
|
description: Custom metadata for this asset reference
|
|
type: object
|
|
required:
|
|
- hash
|
|
- tags
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetCreated'
|
|
description: |
|
|
Asset reference already existed for this user (deduplicated by content
|
|
hash); the existing asset is returned with created_new=false.
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/AssetCreated'
|
|
description: Asset reference created successfully (created_new=true)
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request (bad hash format, invalid tags, etc.)
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Source asset with given hash not found
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error (e.g., disallowed model_type tag)
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Create asset reference from existing hash
|
|
tags:
|
|
- file
|
|
/api/assets/hash/{hash}:
|
|
head:
|
|
description: |
|
|
Checks if an asset exists in the system by its blake3 hash.
|
|
Returns 200 if the asset exists, 404 if it doesn't.
|
|
operationId: checkAssetByHash
|
|
parameters:
|
|
- description: Blake3 hash of the asset in format 'blake3:hex_digest'
|
|
in: path
|
|
name: hash
|
|
required: true
|
|
schema:
|
|
example: blake3:a1b2c3d4e5f67890123456789012345678901234567890123456789012345678
|
|
pattern: ^blake3:[a-f0-9]{64}$
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Asset exists
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid hash format
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
description: Asset not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Check if asset exists by hash
|
|
tags:
|
|
- file
|
|
/api/assets/prune:
|
|
post:
|
|
description: Starts a background job that removes asset entries whose underlying content no longer exists on disk.
|
|
operationId: pruneAssets
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
marked:
|
|
description: Number of assets marked as missing
|
|
type: integer
|
|
status:
|
|
type: string
|
|
type: object
|
|
description: Prune result
|
|
summary: Mark assets whose backing files no longer exist on disk
|
|
/api/assets/seed:
|
|
post:
|
|
description: Starts a background job that scans configured directories and registers assets not yet in the asset database.
|
|
operationId: seedAssets
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
roots:
|
|
description: Root folder paths to scan (if omitted, scans all)
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: object
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
status:
|
|
type: string
|
|
type: object
|
|
description: Seed started
|
|
summary: Trigger asset scan/seed from filesystem
|
|
/api/assets/seed/cancel:
|
|
post:
|
|
description: Requests cancellation of the currently-running asset seed job.
|
|
operationId: cancelAssetSeed
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
status:
|
|
type: string
|
|
type: object
|
|
description: Scan cancelled
|
|
summary: Cancel an in-progress asset scan
|
|
/api/assets/seed/status:
|
|
get:
|
|
description: Returns progress/status of the most recent asset seed job.
|
|
operationId: getAssetSeedStatus
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
description: Scan progress details (files scanned, total, status, etc.)
|
|
type: object
|
|
description: Scan progress
|
|
summary: Get asset scan progress
|
|
/api/assets/tags/refine:
|
|
get:
|
|
description: |
|
|
Returns a histogram of tags appearing on assets matching the given filters.
|
|
Useful for refining asset searches by showing available tags and their counts.
|
|
Only returns tags with non-zero counts (tags that exist on matching assets).
|
|
operationId: getAssetTagHistogram
|
|
parameters:
|
|
- 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.
|
|
Each folder's name is the identifier to pass to /api/experiment/models/{folder}.
|
|
Once the model_type migration is active the names are model_type folder_names
|
|
(e.g. `ultralytics_bbox`); a folder with no folder_name mapping is returned by
|
|
its directory path.
|
|
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
|
|
supports_model_type_tags:
|
|
description: Whether the server supports namespaced model type asset tags
|
|
type: boolean
|
|
type: object
|
|
description: Success
|
|
headers:
|
|
Cache-Control:
|
|
description: Short-lived private cache to deduplicate rapid-fire calls from the frontend
|
|
schema:
|
|
type: string
|
|
Vary:
|
|
description: Cache key includes auth headers so anonymous and authenticated responses are stored separately
|
|
schema:
|
|
type: string
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
- CookieAuth: []
|
|
- {}
|
|
summary: Get server feature flags
|
|
tags:
|
|
- node
|
|
/api/feedback:
|
|
post:
|
|
description: Submit feedback about the ComfyUI service
|
|
operationId: submitFeedback
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FeedbackRequest'
|
|
required: true
|
|
responses:
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/FeedbackResponse'
|
|
description: Feedback submitted successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Submit user feedback
|
|
tags:
|
|
- feedback
|
|
/api/files/mask-layers:
|
|
get:
|
|
description: |
|
|
Given a mask file (any of the 4 layers), returns all related mask layer files.
|
|
This is used by the mask editor to load the paint, mask, and painted layers
|
|
when reopening a previously edited mask.
|
|
operationId: getMaskLayers
|
|
parameters:
|
|
- description: Hash filename of any mask layer file
|
|
in: query
|
|
name: filename
|
|
required: true
|
|
schema:
|
|
example: abc123def456.png
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
mask:
|
|
description: Filename of the mask layer
|
|
nullable: true
|
|
type: string
|
|
paint:
|
|
description: Filename of the paint strokes layer
|
|
nullable: true
|
|
type: string
|
|
painted:
|
|
description: Filename of the painted image layer
|
|
nullable: true
|
|
type: string
|
|
painted_masked:
|
|
description: Filename of the final composite layer
|
|
nullable: true
|
|
type: string
|
|
type: object
|
|
description: Success - Related mask layers returned
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: File not found or not a mask file
|
|
summary: Get related mask layer files
|
|
tags:
|
|
- file
|
|
/api/free:
|
|
post:
|
|
description: Frees GPU memory by unloading models and/or freeing the resident model cache.
|
|
operationId: freeMemory
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
free_memory:
|
|
description: Run garbage collection and free cached memory
|
|
type: boolean
|
|
unload_models:
|
|
description: Unload all models from VRAM/RAM
|
|
type: boolean
|
|
type: object
|
|
responses:
|
|
"200":
|
|
description: Memory freed
|
|
summary: Free GPU memory and/or unload models
|
|
/api/global_subgraphs:
|
|
get:
|
|
description: |
|
|
Returns a list of globally available subgraph blueprints.
|
|
These are pre-built workflow components that can be used as nodes.
|
|
The data field contains a promise that resolves to the full subgraph JSON.
|
|
operationId: getGlobalSubgraphs
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/GlobalSubgraphInfo'
|
|
type: object
|
|
description: Success - Map of subgraph IDs to their metadata
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security: []
|
|
summary: Get available subgraph blueprints
|
|
tags:
|
|
- workflow
|
|
/api/global_subgraphs/{id}:
|
|
get:
|
|
description: Returns the full data for a specific subgraph blueprint by ID
|
|
operationId: getGlobalSubgraph
|
|
parameters:
|
|
- description: The unique identifier of the subgraph blueprint
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GlobalSubgraphData'
|
|
description: Success - Full subgraph data
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Subgraph not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security: []
|
|
summary: Get a specific subgraph blueprint
|
|
tags:
|
|
- workflow
|
|
/api/history:
|
|
post:
|
|
deprecated: true
|
|
description: |
|
|
**Deprecated.** Superseded by the job-management endpoints under
|
|
`/api/jobs`. Planned for removal no earlier than a future major
|
|
release; sunset timeline TBD.
|
|
|
|
Clear all history for the authenticated user or delete specific job IDs.
|
|
Supports clearing all history or deleting specific job IDs.
|
|
operationId: manageHistory
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HistoryManageRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Success - History management operation completed
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Manage execution history
|
|
tags:
|
|
- workflow
|
|
/api/history_v2:
|
|
get:
|
|
deprecated: true
|
|
description: |
|
|
**Deprecated.** Superseded by `GET /api/jobs`, which returns the same
|
|
execution records in a paginated, filterable format. Planned for removal
|
|
no earlier than a future major release; sunset timeline TBD.
|
|
|
|
Retrieve execution history for the authenticated user with pagination support.
|
|
Returns a lightweight history format with filtered prompt data (workflow removed from extra_pnginfo).
|
|
operationId: getHistory
|
|
parameters:
|
|
- description: Maximum number of items to return
|
|
in: query
|
|
name: max_items
|
|
schema:
|
|
type: integer
|
|
- description: Starting position (default 0)
|
|
in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
type: integer
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HistoryResponse'
|
|
description: Success - Execution history retrieved
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get execution history (v2)
|
|
tags:
|
|
- workflow
|
|
/api/history_v2/{prompt_id}:
|
|
get:
|
|
deprecated: true
|
|
description: |
|
|
**Deprecated.** Superseded by `GET /api/jobs/{job_id}`, which returns
|
|
the same execution record. Planned for removal no earlier than a future
|
|
major release; sunset timeline TBD.
|
|
|
|
Retrieve detailed execution history for a specific prompt ID.
|
|
Returns full history data including complete prompt information.
|
|
operationId: getHistoryForPrompt
|
|
parameters:
|
|
- description: The prompt ID to retrieve history for
|
|
in: path
|
|
name: prompt_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/HistoryDetailResponse'
|
|
description: Success - History for prompt retrieved
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Prompt not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get history for specific prompt
|
|
tags:
|
|
- workflow
|
|
/api/i18n:
|
|
get:
|
|
description: Returns translation file URLs contributed by custom nodes, keyed by locale.
|
|
operationId: getI18n
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
description: Nested map of locale to translation key-value pairs
|
|
type: object
|
|
description: Translation map
|
|
summary: Get internationalisation translation strings
|
|
/api/interrupt:
|
|
post:
|
|
deprecated: true
|
|
description: |
|
|
Deprecated. Prefer the jobs-namespace cancel endpoints:
|
|
POST /api/jobs/{job_id}/cancel for a single job, or
|
|
POST /api/jobs/cancel to cancel jobs by ID.
|
|
|
|
Cancels the first active job for the authenticated user (the currently
|
|
running job if there is one, otherwise the next pending job). Takes no
|
|
body and cannot target a specific job — use the jobs-namespace endpoints
|
|
for that.
|
|
operationId: interruptJob
|
|
responses:
|
|
"200":
|
|
description: Success - first active job cancelled, or no active job found
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Interrupt the first active job
|
|
tags:
|
|
- queue
|
|
/api/job/{job_id}/status:
|
|
get:
|
|
deprecated: true
|
|
description: |
|
|
**Deprecated.** Superseded by `GET /api/jobs/{job_id}` (plural path).
|
|
Clients should migrate; the endpoint is retained for backward
|
|
compatibility but will be removed in a future release.
|
|
operationId: getJobStatus
|
|
parameters:
|
|
- description: The unique ID of the job
|
|
in: path
|
|
name: job_id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JobStatusResponse'
|
|
description: Success - Job status returned
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden - job belongs to another user
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Job not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get job status (deprecated)
|
|
tags:
|
|
- job
|
|
/api/jobs:
|
|
get:
|
|
description: |
|
|
Retrieve a paginated list of jobs for the authenticated user.
|
|
Returns lightweight job data optimized for list views.
|
|
Workflow and full outputs are excluded to reduce payload size.
|
|
operationId: listJobs
|
|
parameters:
|
|
- description: Filter by one or more statuses (comma-separated). If not provided, returns all jobs.
|
|
example: pending,in_progress
|
|
in: query
|
|
name: status
|
|
schema:
|
|
type: string
|
|
- description: Filter by workflow ID (exact match)
|
|
example: 550e8400-e29b-41d4-a716-446655440000
|
|
in: query
|
|
name: workflow_id
|
|
schema:
|
|
type: string
|
|
- description: Filter by output media type (only applies to completed jobs with outputs)
|
|
example: image
|
|
in: query
|
|
name: output_type
|
|
schema:
|
|
enum:
|
|
- image
|
|
- video
|
|
- audio
|
|
- 3d
|
|
type: string
|
|
- description: Field to sort by (create_time = when job was submitted, execution_time = how long workflow took to run)
|
|
example: execution_time
|
|
in: query
|
|
name: sort_by
|
|
schema:
|
|
default: create_time
|
|
enum:
|
|
- create_time
|
|
- execution_time
|
|
type: string
|
|
- description: Sort direction (asc = ascending, desc = descending)
|
|
in: query
|
|
name: sort_order
|
|
schema:
|
|
default: desc
|
|
enum:
|
|
- asc
|
|
- desc
|
|
type: string
|
|
- description: |
|
|
Opaque cursor for keyset pagination. Pass the `next_cursor` value
|
|
from a previous response to fetch the next page.
|
|
Cursor pagination is supported only when `sort_by=create_time`
|
|
(default). If `sort_by=execution_time`, `after` is ignored and
|
|
offset/limit pagination is used.
|
|
Cursors are opaque base64url payloads — clients should treat them
|
|
as strings and not parse the contents.
|
|
example: eyJzIjoiY3JlYXRlX3RpbWUiLCJ2IjoiMTcxNjIwMDAwMDAwMDAwMCIsImlkIjoiYTFiMmMzZDQtZTVmNi03YTg5LWIwYzEtZDJlM2Y0YTViNmM3In0
|
|
in: query
|
|
name: after
|
|
schema:
|
|
type: string
|
|
- deprecated: true
|
|
description: 'Pagination offset (0-based). Deprecated: prefer cursor-based pagination via `after`.'
|
|
in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
minimum: 0
|
|
type: integer
|
|
- description: Maximum items per page (1-1000)
|
|
in: query
|
|
name: limit
|
|
schema:
|
|
default: 100
|
|
maximum: 1000
|
|
minimum: 1
|
|
type: integer
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JobsListResponse'
|
|
description: Success - Jobs retrieved
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad request (e.g. malformed pagination cursor).
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: List jobs with pagination and filtering
|
|
tags:
|
|
- workflow
|
|
/api/jobs/{job_id}:
|
|
get:
|
|
description: |
|
|
Retrieve complete details for a specific job including workflow and outputs.
|
|
Used for detail views, workflow re-execution, and debugging.
|
|
operationId: getJobDetail
|
|
parameters:
|
|
- description: Job identifier (UUID)
|
|
in: path
|
|
name: job_id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
- description: |
|
|
When present, each output item in the response receives a `short_url` field containing a short link for that asset. Omit this parameter (the default) to receive a response identical to the no-param baseline. The value selects the link's lifetime and auth model: use `ephemeral_tool_chain` for short-lived (≤5 minute) machine-to-machine handoffs — these are public bearer links where the link ID itself is the credential, so anyone holding the link can resolve it (intended for pasting into an agent/MCP tool chain); use `default` for durable (30 day) human-revisitable links, which are owner-gated and resolvable only by the authenticated owner. Links are always minted under the authenticated request owner's identity; the auth model is selected by the server and is never settable by the caller.
|
|
in: query
|
|
name: short_link
|
|
schema:
|
|
enum:
|
|
- ephemeral_tool_chain
|
|
- default
|
|
type: string
|
|
x-runtime:
|
|
- cloud
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JobDetailResponse'
|
|
description: Success - Job details retrieved
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden - Job does not belong to user
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Job not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get full job details
|
|
tags:
|
|
- workflow
|
|
/api/jobs/{job_id}/cancel:
|
|
post:
|
|
description: |
|
|
Cancel a specific job for the authenticated user.
|
|
|
|
Idempotent: a job that is already in a terminal state (completed, failed,
|
|
cancelled) or already cancelling is treated as a successful no-op and
|
|
returns 200. Only truly missing or cross-user jobs return 404.
|
|
operationId: cancelJob
|
|
parameters:
|
|
- description: Job identifier (UUID)
|
|
in: path
|
|
name: job_id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JobCancelResponse'
|
|
description: Success - Cancel request accepted (or job was already terminal)
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad Request - job_id is not a valid UUID (emitted by request validation before the handler runs)
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Job not found for this user
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error - cancellation failed
|
|
summary: Cancel a job
|
|
tags:
|
|
- workflow
|
|
/api/jobs/cancel:
|
|
post:
|
|
description: |
|
|
Cancel one or more jobs for the authenticated user in a single request.
|
|
|
|
State-agnostic: cancels both pending and running jobs (both transition to
|
|
the cancelled state via the same mechanism as the single-job endpoint).
|
|
|
|
Idempotent per job: a job already in a terminal or cancelling state is a
|
|
no-op and simply will not appear in the returned `cancelled` list.
|
|
|
|
Fail-fast on unknown IDs: if any provided job ID does not exist for this
|
|
user, the request returns 404 and no jobs are cancelled. This surfaces
|
|
bad IDs to the caller rather than silently dropping them.
|
|
|
|
This is the canonical batch-cancel endpoint. The delete operation on
|
|
POST /api/queue is deprecated in favour of this.
|
|
operationId: cancelJobs
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JobsCancelRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/JobsCancelResponse'
|
|
description: Success - cancel requests dispatched (or jobs were already terminal)
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad Request - job_ids is missing, empty, exceeds the maximum count, or contains an invalid UUID
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: One or more job IDs not found for this user (no jobs cancelled)
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error - cancellation failed
|
|
summary: Cancel multiple jobs
|
|
tags:
|
|
- workflow
|
|
/api/node_replacements:
|
|
get:
|
|
description: |
|
|
Returns mappings of unsupported node class names to their cloud-installed replacements.
|
|
Used by the frontend to offer "Quick Fix" when a workflow contains missing nodes.
|
|
operationId: getNodeReplacements
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
type: object
|
|
description: Success - Node replacement mappings
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security: []
|
|
summary: Get node replacement mappings
|
|
tags:
|
|
- node
|
|
/api/object_info:
|
|
get:
|
|
description: Returns information about all available nodes
|
|
operationId: getNodeInfo
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties:
|
|
$ref: '#/components/schemas/NodeInfo'
|
|
type: object
|
|
description: Success
|
|
summary: Get all node information
|
|
tags:
|
|
- node
|
|
/api/prompt:
|
|
get:
|
|
description: Returns information about the current prompt in the execution queue
|
|
operationId: getPromptInfo
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptInfo'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get information about current prompt execution
|
|
tags:
|
|
- workflow
|
|
post:
|
|
description: |
|
|
Submit a workflow to be executed by the backend.
|
|
The workflow is a JSON object describing the nodes and their connections.
|
|
operationId: executePrompt
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptResponse'
|
|
description: Success - Prompt accepted
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptErrorResponse'
|
|
description: Invalid prompt
|
|
"402":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptErrorResponse'
|
|
description: Payment required - Insufficient credits
|
|
"413":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PromptErrorResponse'
|
|
description: Workflow JSON too large
|
|
"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:
|
|
deprecated: true
|
|
description: |
|
|
Deprecated. Prefer the jobs-namespace cancel endpoints:
|
|
POST /api/jobs/cancel for cancelling jobs by ID, and
|
|
POST /api/jobs/{job_id}/cancel for a single job.
|
|
|
|
Cancel specific jobs by ID (the `delete` field) or clear all pending
|
|
jobs in the queue (the `clear` field). Despite the `delete` naming, this
|
|
does not delete anything — listed jobs transition to the cancelled state,
|
|
and `delete` cancels both pending and running jobs (not pending-only as
|
|
previously documented). Job-by-ID cancellation is superseded by
|
|
POST /api/jobs/cancel; `clear` has no jobs-namespace replacement yet.
|
|
operationId: manageQueue
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueueManageRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/QueueManageResponse'
|
|
description: Success
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Manage queue operations
|
|
tags:
|
|
- queue
|
|
/api/settings:
|
|
get:
|
|
description: Returns all settings for the authenticated user
|
|
operationId: getAllSettings
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
description: User settings as key-value pairs
|
|
type: object
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
summary: Get all user settings
|
|
tags:
|
|
- settings
|
|
post:
|
|
description: Update multiple settings (merge with existing)
|
|
operationId: updateMultipleSettings
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
description: Settings to update as key-value pairs
|
|
type: object
|
|
text/plain:
|
|
schema:
|
|
description: JSON string of settings to update
|
|
type: string
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties: true
|
|
description: Updated user settings
|
|
type: object
|
|
description: Success
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
summary: Update multiple settings
|
|
tags:
|
|
- settings
|
|
/api/settings/{id}:
|
|
get:
|
|
description: Returns a specific setting value by its id
|
|
operationId: getSettingById
|
|
parameters:
|
|
- description: Setting id to retrieve
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: Setting value response
|
|
properties:
|
|
value:
|
|
description: The setting value
|
|
type: object
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Setting not found
|
|
summary: Get a specific setting by id
|
|
tags:
|
|
- settings
|
|
post:
|
|
description: Update a specific setting by its id
|
|
operationId: updateSettingById
|
|
parameters:
|
|
- description: Setting id to update
|
|
in: path
|
|
name: id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: New value for the setting
|
|
text/plain:
|
|
schema:
|
|
description: JSON string of the new setting value
|
|
type: string
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: Updated setting value response
|
|
properties:
|
|
value:
|
|
description: The updated setting value
|
|
type: object
|
|
description: Success
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
summary: Update a specific setting by id
|
|
tags:
|
|
- settings
|
|
/api/system_stats:
|
|
get:
|
|
description: Returns system statistics including ComfyUI version, device info, and system resources
|
|
operationId: getSystemStats
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/SystemStatsResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
security: []
|
|
summary: Get system statistics
|
|
tags:
|
|
- system
|
|
/api/tags:
|
|
get:
|
|
description: |
|
|
Retrieves a list of all tags used across assets.
|
|
Includes usage counts and filtering options.
|
|
operationId: listTags
|
|
parameters:
|
|
- description: Filter tags by prefix
|
|
in: query
|
|
name: prefix
|
|
schema:
|
|
type: string
|
|
- description: Maximum number of tags to return (1-1000)
|
|
in: query
|
|
name: limit
|
|
schema:
|
|
default: 100
|
|
maximum: 1000
|
|
minimum: 1
|
|
type: integer
|
|
- description: Number of tags to skip for pagination
|
|
in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
minimum: 0
|
|
type: integer
|
|
- description: Sort order for tags
|
|
in: query
|
|
name: order
|
|
schema:
|
|
default: count_desc
|
|
enum:
|
|
- count_desc
|
|
- name_asc
|
|
type: string
|
|
- description: Include tags with zero usage count
|
|
in: query
|
|
name: include_zero
|
|
schema:
|
|
default: false
|
|
type: boolean
|
|
- description: Whether to include public/shared assets when counting tags
|
|
in: query
|
|
name: include_public
|
|
schema:
|
|
default: true
|
|
type: boolean
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ListTagsResponse'
|
|
description: Tags retrieved successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: List all tags
|
|
tags:
|
|
- file
|
|
/api/tasks:
|
|
get:
|
|
description: |
|
|
Retrieve a paginated list of background tasks for the authenticated user.
|
|
Supports filtering by task type, status, and creation time.
|
|
operationId: listTasks
|
|
parameters:
|
|
- description: Filter by task type name (exact match)
|
|
example: model_upload
|
|
in: query
|
|
name: task_name
|
|
schema:
|
|
type: string
|
|
- description: Filter by idempotency key (exact match). For best performance, specify task_name as well.
|
|
example: upload-model-abc123
|
|
in: query
|
|
name: idempotency_key
|
|
schema:
|
|
type: string
|
|
- description: Filter by one or more statuses (comma-separated)
|
|
example: created,running
|
|
in: query
|
|
name: status
|
|
schema:
|
|
type: string
|
|
- description: Filter tasks created after this timestamp (RFC3339 format)
|
|
example: "2024-01-01T00:00:00Z"
|
|
in: query
|
|
name: created_after
|
|
schema:
|
|
format: date-time
|
|
type: string
|
|
- description: Filter tasks created before this timestamp (RFC3339 format)
|
|
example: "2024-12-31T23:59:59Z"
|
|
in: query
|
|
name: created_before
|
|
schema:
|
|
format: date-time
|
|
type: string
|
|
- description: Sort direction (asc = ascending, desc = descending by create_time)
|
|
in: query
|
|
name: sort_order
|
|
schema:
|
|
default: desc
|
|
enum:
|
|
- asc
|
|
- desc
|
|
type: string
|
|
- description: Pagination offset (0-based)
|
|
in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
minimum: 0
|
|
type: integer
|
|
- description: Maximum items per page (1-100)
|
|
in: query
|
|
name: limit
|
|
schema:
|
|
default: 20
|
|
maximum: 100
|
|
minimum: 1
|
|
type: integer
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TasksListResponse'
|
|
description: Success - Tasks retrieved
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error - Invalid filter values
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: List background tasks
|
|
tags:
|
|
- task
|
|
/api/tasks/{task_id}:
|
|
get:
|
|
description: |
|
|
Retrieve full details for a specific background task.
|
|
operationId: getTask
|
|
parameters:
|
|
- description: Task identifier (UUID)
|
|
in: path
|
|
name: task_id
|
|
required: true
|
|
schema:
|
|
format: uuid
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/TaskResponse'
|
|
description: Success - Task details retrieved
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized - Authentication required
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Task not found (also returned for ownership failures to avoid leaking task existence)
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get task details
|
|
tags:
|
|
- task
|
|
/api/upload/image:
|
|
post:
|
|
description: |
|
|
Upload an image file to cloud storage.
|
|
|
|
Image limits:
|
|
- Maximum file size: 50 MB
|
|
- Maximum width/height per edge: 16384 px
|
|
- Maximum total pixel count: 64 megapixels (67108864 pixels)
|
|
|
|
Uploads that exceed any of these limits are rejected with HTTP 400.
|
|
operationId: uploadImage
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
properties:
|
|
image:
|
|
description: The image file to upload
|
|
format: binary
|
|
type: string
|
|
overwrite:
|
|
description: Whether to overwrite existing file (true/false)
|
|
type: string
|
|
subfolder:
|
|
description: Optional subfolder path
|
|
type: string
|
|
type:
|
|
description: Upload type (defaults to "output")
|
|
type: string
|
|
required:
|
|
- image
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
name:
|
|
description: Filename of the uploaded image
|
|
type: string
|
|
subfolder:
|
|
description: Subfolder path where image was saved
|
|
type: string
|
|
type:
|
|
description: Type of upload (e.g., "output")
|
|
type: string
|
|
type: object
|
|
description: Image uploaded successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Upload an image file
|
|
tags:
|
|
- file
|
|
/api/upload/mask:
|
|
post:
|
|
description: |
|
|
Upload a mask image to be applied to an existing image.
|
|
|
|
Image limits apply to both the uploaded mask and the referenced
|
|
original image:
|
|
- Maximum file size: 50 MB
|
|
- Maximum width/height per edge: 16384 px
|
|
- Maximum total pixel count: 64 megapixels (67108864 pixels)
|
|
|
|
Uploads that exceed any of these limits are rejected with HTTP 400.
|
|
operationId: uploadMask
|
|
requestBody:
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
properties:
|
|
image:
|
|
description: The mask image file to upload
|
|
format: binary
|
|
type: string
|
|
original_ref:
|
|
description: JSON string containing reference to the original image
|
|
type: string
|
|
required:
|
|
- image
|
|
- original_ref
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
name:
|
|
description: Filename of the uploaded mask
|
|
type: string
|
|
subfolder:
|
|
description: Subfolder path where mask was saved
|
|
type: string
|
|
type:
|
|
description: Type of upload (e.g., "output")
|
|
type: string
|
|
type: object
|
|
description: Mask uploaded successfully
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Upload a mask image
|
|
tags:
|
|
- file
|
|
/api/user:
|
|
get:
|
|
description: Returns information about the currently authenticated user
|
|
operationId: getUser
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
summary: Get current user information
|
|
tags:
|
|
- user
|
|
/api/userdata:
|
|
get:
|
|
description: Returns a list of user data files in the specified directory, optionally recursively and with full metadata.
|
|
operationId: getUserdata
|
|
parameters:
|
|
- description: The directory to list files from.
|
|
in: query
|
|
name: dir
|
|
schema:
|
|
type: string
|
|
- description: Whether to list files recursively.
|
|
in: query
|
|
name: recurse
|
|
schema:
|
|
default: false
|
|
type: boolean
|
|
- description: Whether to split file information by type.
|
|
in: query
|
|
name: split
|
|
schema:
|
|
default: false
|
|
type: boolean
|
|
- description: Whether to return full file metadata.
|
|
in: query
|
|
name: full_info
|
|
schema:
|
|
default: false
|
|
type: boolean
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/GetUserDataResponseFull'
|
|
description: A list of user data files.
|
|
"400":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Bad request (e.g., invalid filename).
|
|
"401":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Unauthorized.
|
|
"404":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: File not found or invalid path.
|
|
"500":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: General error
|
|
summary: List user data files
|
|
tags:
|
|
- user
|
|
/api/userdata/{file}:
|
|
delete:
|
|
description: |
|
|
Delete a user data file from the database. The file parameter should be
|
|
the relative path within the user's data directory.
|
|
operationId: deleteUserdataFile
|
|
parameters:
|
|
- description: The file path to delete (URL encoded if necessary).
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"204":
|
|
description: File deleted successfully (No Content).
|
|
"401":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Unauthorized.
|
|
"404":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: File not found.
|
|
"500":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Internal server error.
|
|
summary: Delete a user data file
|
|
tags:
|
|
- user
|
|
get:
|
|
description: Returns the requested user data file if it exists.
|
|
operationId: getUserdataFile
|
|
parameters:
|
|
- description: The filename of the user data to retrieve.
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
format: binary
|
|
type: string
|
|
description: Successfully retrieved the file.
|
|
"400":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Bad request (e.g., invalid filename).
|
|
"401":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Unauthorized.
|
|
"404":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: File not found or invalid path.
|
|
"500":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: General error
|
|
summary: Get user data file
|
|
tags:
|
|
- user
|
|
post:
|
|
description: |
|
|
Upload a file to a user's data directory. Optional query parameters allow
|
|
control over overwrite behavior and response detail.
|
|
operationId: postUserdataFile
|
|
parameters:
|
|
- description: The target file path (URL encoded if necessary).
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- description: If "false", prevents overwriting existing files. Defaults to "true".
|
|
in: query
|
|
name: overwrite
|
|
schema:
|
|
default: "true"
|
|
enum:
|
|
- "true"
|
|
- "false"
|
|
type: string
|
|
- description: If "true", returns detailed file info; if "false", returns only the relative path.
|
|
in: query
|
|
name: full_info
|
|
schema:
|
|
default: "false"
|
|
enum:
|
|
- "true"
|
|
- "false"
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
format: binary
|
|
type: string
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserDataResponseFull'
|
|
description: File uploaded successfully.
|
|
"400":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Missing or invalid 'file' parameter.
|
|
"401":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Unauthorized.
|
|
"403":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: The requested path is not allowed.
|
|
"409":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: File already exists and overwrite is set to false.
|
|
"500":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: General error
|
|
summary: Upload or update a user data file
|
|
tags:
|
|
- user
|
|
/api/userdata/{file}/move/{dest}:
|
|
post:
|
|
description: |
|
|
Move or rename a file within a user's data directory, with options for
|
|
controlling overwrite behavior and response format.
|
|
operationId: moveUserdataFile
|
|
parameters:
|
|
- description: The source file path (URL encoded if necessary).
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- description: The destination file path (URL encoded if necessary).
|
|
in: path
|
|
name: dest
|
|
required: true
|
|
schema:
|
|
type: string
|
|
- description: If "false", prevents overwriting existing files. Defaults to "true".
|
|
in: query
|
|
name: overwrite
|
|
schema:
|
|
default: "true"
|
|
enum:
|
|
- "true"
|
|
- "false"
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UserDataResponseFull'
|
|
description: File moved successfully.
|
|
"400":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Missing or invalid parameters.
|
|
"401":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Unauthorized.
|
|
"404":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Source file not found.
|
|
"409":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Destination file already exists and overwrite is set to false.
|
|
"500":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: General error
|
|
summary: Move or rename a user data file
|
|
tags:
|
|
- user
|
|
/api/userdata/{file}/publish:
|
|
get:
|
|
description: Returns the publish status and share info for a workflow identified by its userdata path.
|
|
operationId: getUserdataFilePublish
|
|
parameters:
|
|
- description: The workflow file path within the user's data directory (URL encoded if necessary).
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowPublishInfo'
|
|
description: Publish info (publish_time is null if never published)
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get publish info for a workflow file
|
|
tags:
|
|
- workflows
|
|
post:
|
|
description: Creates a new published_workflow record from the latest version and snapshots the provided assets.
|
|
operationId: postUserdataFilePublish
|
|
parameters:
|
|
- description: The workflow file path within the user's data directory (URL encoded if necessary).
|
|
in: path
|
|
name: file
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PublishWorkflowAssetsRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowPublishInfo'
|
|
description: Workflow published
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Bad request
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Publish a workflow file
|
|
tags:
|
|
- workflows
|
|
/api/users:
|
|
get:
|
|
description: |
|
|
ComfyUI legacy users endpoint. Returns information about how user
|
|
data is stored. In cloud this is always server-managed, so callers
|
|
receive a constant response indicating server-side storage.
|
|
operationId: getUsersInfo
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
migrated:
|
|
description: Whether user data has been migrated (always true in cloud)
|
|
type: boolean
|
|
storage:
|
|
description: Where user data is stored (always "server" in cloud)
|
|
type: string
|
|
required:
|
|
- storage
|
|
- migrated
|
|
type: object
|
|
description: Userdata storage information
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
summary: ComfyUI userdata storage info
|
|
tags:
|
|
- user
|
|
/api/vhs/queryvideo:
|
|
get:
|
|
description: |
|
|
VHS custom node endpoint that returns metadata about a video file
|
|
(frame count, fps, resolution, duration). Currently returns default
|
|
placeholder values; real ffprobe integration is a follow-up.
|
|
operationId: getVhsQueryVideo
|
|
parameters:
|
|
- description: Name of the video file to query
|
|
in: query
|
|
name: filename
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
source:
|
|
description: Source video metadata
|
|
properties:
|
|
duration:
|
|
description: Duration in seconds
|
|
type: number
|
|
fps:
|
|
description: Frames per second
|
|
type: number
|
|
frames:
|
|
description: Total frame count
|
|
type: integer
|
|
size:
|
|
description: '[width, height] in pixels'
|
|
items:
|
|
type: integer
|
|
maxItems: 2
|
|
minItems: 2
|
|
type: array
|
|
required:
|
|
- size
|
|
- fps
|
|
- frames
|
|
- duration
|
|
type: object
|
|
required:
|
|
- source
|
|
type: object
|
|
description: Video metadata
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: |
|
|
Missing required query parameter. Produced by the oapi-codegen
|
|
wrapper via echo.NewHTTPError; the custom Echo HTTPErrorHandler
|
|
normalizes it to the standard ErrorResponse {code, message} shape
|
|
(BE-1178).
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
- CookieAuth: []
|
|
summary: Query VHS video metadata
|
|
tags:
|
|
- file
|
|
/api/view:
|
|
get:
|
|
description: |
|
|
Retrieve and view a file from the ComfyUI file system.
|
|
This endpoint is typically used to view generated images or other output files.
|
|
Cookie auth is allowed on this endpoint because it's used by img/video tags in browsers.
|
|
operationId: viewFile
|
|
parameters:
|
|
- description: Name of the file to view
|
|
in: query
|
|
name: filename
|
|
required: true
|
|
schema:
|
|
example: ComfyUI_00004_.png
|
|
type: string
|
|
- description: Subfolder path where the file is located
|
|
in: query
|
|
name: subfolder
|
|
schema:
|
|
example: tests/foo/bar
|
|
type: string
|
|
- description: Type of file (e.g., output, input, temp)
|
|
in: query
|
|
name: type
|
|
schema:
|
|
example: output
|
|
type: string
|
|
- description: Full path to the file (used for temp files)
|
|
in: query
|
|
name: fullpath
|
|
schema:
|
|
type: string
|
|
- description: Format of the file
|
|
in: query
|
|
name: format
|
|
schema:
|
|
type: string
|
|
- description: Frame rate for video files
|
|
in: query
|
|
name: frame_rate
|
|
schema:
|
|
type: integer
|
|
- description: Workflow identifier
|
|
in: query
|
|
name: workflow
|
|
schema:
|
|
type: string
|
|
- description: Timestamp parameter
|
|
in: query
|
|
name: timestamp
|
|
schema:
|
|
example: 1234567890
|
|
type: integer
|
|
- description: |
|
|
Image channel to extract from PNG images.
|
|
- 'rgb': Return only RGB channels (alpha set to fully opaque)
|
|
- 'a' or 'alpha': Return alpha channel as grayscale image
|
|
- If not specified, return original image unchanged via redirect
|
|
in: query
|
|
name: channel
|
|
schema:
|
|
example: rgb
|
|
type: string
|
|
- description: |
|
|
Maximum dimension (width or height) to resize the image to, preserving aspect ratio.
|
|
The image is fit within a res x res box. Returns a JPEG thumbnail.
|
|
Only applies to raster image files (PNG, JPEG, WebP, GIF).
|
|
in: query
|
|
name: res
|
|
schema:
|
|
example: 256
|
|
maximum: 1024
|
|
minimum: 64
|
|
type: integer
|
|
responses:
|
|
"200":
|
|
content:
|
|
image/jpeg:
|
|
schema:
|
|
description: Resized JPEG thumbnail (returned when res parameter is used)
|
|
format: binary
|
|
type: string
|
|
image/png:
|
|
schema:
|
|
description: Processed PNG image with extracted channel
|
|
format: binary
|
|
type: string
|
|
description: Success - File content returned (used when channel or res parameter is present)
|
|
"302":
|
|
description: Redirect to GCS signed URL
|
|
headers:
|
|
Cache-Control:
|
|
description: Cache directive for the redirect response
|
|
schema:
|
|
type: string
|
|
Location:
|
|
description: Signed URL to access the file in GCS
|
|
schema:
|
|
type: string
|
|
Vary:
|
|
description: Headers that affect response caching
|
|
schema:
|
|
type: string
|
|
"400":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Invalid request parameters
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: File not found or unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
- CookieAuth: []
|
|
summary: View a file
|
|
tags:
|
|
- file
|
|
/api/workflow_templates:
|
|
get:
|
|
description: Returns available workflow templates
|
|
operationId: getWorkflowTemplates
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: Empty object for workflow templates
|
|
type: object
|
|
description: Success
|
|
security: []
|
|
summary: Get available workflow templates
|
|
tags:
|
|
- workflow
|
|
/api/workflows:
|
|
get:
|
|
description: Returns a paginated list of workflows for the authenticated user in the current workspace.
|
|
operationId: listWorkflows
|
|
parameters:
|
|
- in: query
|
|
name: limit
|
|
schema:
|
|
default: 20
|
|
maximum: 100
|
|
type: integer
|
|
- in: query
|
|
name: offset
|
|
schema:
|
|
default: 0
|
|
type: integer
|
|
- description: Search workflows by name (case-insensitive substring match)
|
|
in: query
|
|
name: name
|
|
schema:
|
|
type: string
|
|
- description: Filter by default view type
|
|
in: query
|
|
name: default_view
|
|
schema:
|
|
enum:
|
|
- workflow
|
|
- app
|
|
type: string
|
|
- description: Sort field
|
|
in: query
|
|
name: sort
|
|
schema:
|
|
default: create_time
|
|
enum:
|
|
- create_time
|
|
- update_time
|
|
- name
|
|
type: string
|
|
- description: Sort order
|
|
in: query
|
|
name: order
|
|
schema:
|
|
default: desc
|
|
enum:
|
|
- asc
|
|
- desc
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowListResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: List workflows
|
|
tags:
|
|
- workflows
|
|
post:
|
|
description: Creates a new workflow with its first version.
|
|
operationId: createWorkflow
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateWorkflowRequest'
|
|
required: true
|
|
responses:
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowResponse'
|
|
description: Workflow created successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Create a new workflow
|
|
tags:
|
|
- workflows
|
|
/api/workflows/{workflow_id}:
|
|
delete:
|
|
description: Soft-deletes a workflow.
|
|
operationId: deleteWorkflow
|
|
parameters:
|
|
- description: The UUID of the workflow to delete.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"204":
|
|
description: Workflow deleted successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Delete workflow
|
|
tags:
|
|
- workflows
|
|
get:
|
|
description: Retrieves workflow metadata by ID.
|
|
operationId: getWorkflow
|
|
parameters:
|
|
- description: The UUID of the workflow.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get workflow
|
|
tags:
|
|
- workflows
|
|
patch:
|
|
description: Updates mutable workflow metadata (name, description, default_view).
|
|
operationId: updateWorkflow
|
|
parameters:
|
|
- description: The UUID of the workflow to update.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/UpdateWorkflowRequest'
|
|
required: true
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Update workflow metadata
|
|
tags:
|
|
- workflows
|
|
/api/workflows/{workflow_id}/content:
|
|
get:
|
|
description: Retrieves the latest version of a workflow and its JSON content.
|
|
operationId: getWorkflowContent
|
|
parameters:
|
|
- description: The UUID of the workflow whose content should be retrieved.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowVersionContentResponse'
|
|
description: Success
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get workflow content
|
|
tags:
|
|
- workflows
|
|
/api/workflows/{workflow_id}/fork:
|
|
post:
|
|
description: Creates a new workflow by forking from an existing version.
|
|
operationId: forkWorkflow
|
|
parameters:
|
|
- description: The UUID of the source workflow to fork from.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ForkWorkflowRequest'
|
|
required: true
|
|
responses:
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowResponse'
|
|
description: Workflow forked successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Source workflow or version not found
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Fork a workflow
|
|
tags:
|
|
- workflows
|
|
/api/workflows/{workflow_id}/versions:
|
|
post:
|
|
description: Creates a new workflow version with updated workflow JSON. Uses optimistic concurrency via base_version.
|
|
operationId: createWorkflowVersion
|
|
parameters:
|
|
- description: The UUID of the workflow to create a new version for.
|
|
in: path
|
|
name: workflow_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/CreateWorkflowVersionRequest'
|
|
required: true
|
|
responses:
|
|
"201":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/WorkflowVersionResponse'
|
|
description: Version created successfully
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"403":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Forbidden - not the workflow owner
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow not found
|
|
"409":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Version conflict - base_version does not match latest
|
|
"422":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Validation error
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Create a new version
|
|
tags:
|
|
- workflows
|
|
/api/workflows/published/{share_id}:
|
|
get:
|
|
description: |
|
|
Returns the published workflow details including the status of each
|
|
published asset relative to the caller's library. Authentication is required.
|
|
operationId: getPublishedWorkflow
|
|
parameters:
|
|
- description: The share ID of the published workflow.
|
|
in: path
|
|
name: share_id
|
|
required: true
|
|
schema:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/PublishedWorkflowDetail'
|
|
description: Published workflow details with asset statuses
|
|
"401":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Unauthorized
|
|
"404":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Share not found
|
|
"413":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Workflow JSON too large
|
|
"500":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: '#/components/schemas/ErrorResponse'
|
|
description: Internal server error
|
|
summary: Get a published workflow by share ID
|
|
tags:
|
|
- workflows
|
|
/health:
|
|
get:
|
|
description: |
|
|
Returns `200 OK` if the database is reachable and dynamic config has
|
|
loaded, otherwise `503 Service Unavailable`. Used by the GKE ingress
|
|
for health checks. Response body is plain text for probe simplicity.
|
|
operationId: getHealth
|
|
responses:
|
|
"200":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
example: OK
|
|
type: string
|
|
description: Service is healthy
|
|
"503":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
example: Service Unavailable
|
|
type: string
|
|
description: Service is unhealthy
|
|
security: []
|
|
summary: Health probe for Kubernetes readiness/liveness
|
|
tags:
|
|
- system
|
|
/internal/folder_paths:
|
|
get:
|
|
description: Returns the filesystem paths ComfyUI loads models and assets from, keyed by folder type.
|
|
operationId: getInternalFolderPaths
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
additionalProperties:
|
|
items:
|
|
items:
|
|
type: string
|
|
type: array
|
|
type: array
|
|
description: Map of folder type name to list of path entries
|
|
type: object
|
|
description: Dictionary of folder type to paths
|
|
summary: Get configured folder paths
|
|
/internal/logs:
|
|
get:
|
|
description: Returns ComfyUI log entries from the in-memory log buffer.
|
|
operationId: getInternalLogs
|
|
responses:
|
|
"200":
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
description: Log text
|
|
summary: Get server logs as text
|
|
/internal/logs/raw:
|
|
get:
|
|
description: Returns the raw ComfyUI log buffer plus size metadata.
|
|
operationId: getInternalLogsRaw
|
|
responses:
|
|
"200":
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
entries:
|
|
items:
|
|
properties:
|
|
m:
|
|
description: Message
|
|
type: string
|
|
t:
|
|
description: Timestamp
|
|
type: number
|
|
type: object
|
|
type: array
|
|
size:
|
|
properties:
|
|
cols:
|
|
type: integer
|
|
rows:
|
|
type: integer
|
|
type: object
|
|
type: object
|
|
description: Structured log data
|
|
summary: Get raw structured log entries
|
|
/internal/logs/subscribe:
|
|
patch:
|
|
description: Subscribes or unsubscribes the current client from live log streaming over the WebSocket.
|
|
operationId: subscribeToLogs
|
|
requestBody:
|
|
content:
|
|
application/json:
|
|
schema:
|
|
properties:
|
|
clientId:
|
|
description: WebSocket client ID
|
|
type: string
|
|
enabled:
|
|
description: Enable or disable log streaming for this client
|
|
type: boolean
|
|
required:
|
|
- clientId
|
|
- enabled
|
|
type: object
|
|
required: true
|
|
responses:
|
|
"200":
|
|
description: Subscription updated
|
|
summary: Subscribe or unsubscribe a WebSocket client to log streaming
|
|
security:
|
|
- ApiKeyAuth: []
|
|
- BearerAuth: []
|
|
servers:
|
|
- description: Default ComfyUI server
|
|
url: /
|
|
tags:
|
|
- description: Workflow execution and management
|
|
name: workflow
|
|
- description: Node information
|
|
name: node
|
|
- description: File operations
|
|
name: file
|
|
- description: User settings management
|
|
name: settings
|
|
- description: User feedback management
|
|
name: feedback
|
|
- description: System operations and monitoring
|
|
name: system
|
|
- description: User information and management
|
|
name: user
|
|
- description: Background task management
|
|
name: task
|
|
- description: Workflow storage and version management
|
|
name: workflows
|
|
- description: Job queue state and control
|
|
name: queue
|
|
- description: Job lifecycle queries
|
|
name: job
|