mirror of
https://github.com/comfyanonymous/ComfyUI.git
synced 2026-04-20 15:32:32 +08:00
15d68e78dd
Adds a comprehensive OpenAPI 3.1 spec documenting all HTTP endpoints exposed by ComfyUI's server, including prompt execution, queue management, file uploads, userdata, settings, system stats, object info, assets, and internal routes. The spec was validated against the source code with adversarial review from multiple models, and passes Spectral linting with zero errors. Also removes openapi.yaml from .gitignore so the spec is tracked.
3195 lines
90 KiB
YAML
3195 lines
90 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: ComfyUI API
|
|
description: |
|
|
API for ComfyUI - A powerful and modular stable diffusion GUI and backend.
|
|
|
|
This API allows you to interact with ComfyUI programmatically, including:
|
|
- Submitting and managing workflow executions
|
|
- Querying node/object information
|
|
- Uploading and viewing files
|
|
- Managing user settings and data
|
|
- Asset management (feature-gated)
|
|
|
|
## Dual-path routing
|
|
Every route registered via `self.routes` in the ComfyUI server is available at
|
|
both its bare path (e.g. `/prompt`) and an `/api`-prefixed path (e.g. `/api/prompt`).
|
|
This spec uses the `/api`-prefixed versions as canonical.
|
|
|
|
## Multi-user mode
|
|
When ComfyUI is started with `--multi-user`, the `Comfy-User` header identifies
|
|
the active user for settings, userdata, and history isolation. This is **not** a
|
|
security mechanism — it is an organisational convenience with no authentication
|
|
or authorisation behind it.
|
|
version: 1.0.0
|
|
license:
|
|
name: GNU General Public License v3.0
|
|
url: https://github.com/comfyanonymous/ComfyUI/blob/master/LICENSE
|
|
|
|
servers:
|
|
- url: /
|
|
description: Default ComfyUI server (typically http://127.0.0.1:8188)
|
|
|
|
tags:
|
|
- name: prompt
|
|
description: Workflow submission and prompt info
|
|
- name: queue
|
|
description: Queue inspection and management
|
|
- name: history
|
|
description: Execution history
|
|
- name: upload
|
|
description: File upload endpoints
|
|
- name: view
|
|
description: File viewing / download
|
|
- name: system
|
|
description: System stats and feature flags
|
|
- name: node
|
|
description: Node / object_info definitions
|
|
- name: model
|
|
description: Model folder and file listing
|
|
- name: user
|
|
description: User management (multi-user mode)
|
|
- name: userdata
|
|
description: Per-user file storage
|
|
- name: settings
|
|
description: Per-user settings
|
|
- name: extensions
|
|
description: Frontend extension JS files
|
|
- name: subgraph
|
|
description: Global subgraph blueprints
|
|
- name: internal
|
|
description: Internal / debug endpoints
|
|
- name: assets
|
|
description: Asset management (feature-gated behind enable-assets)
|
|
|
|
paths:
|
|
# ---------------------------------------------------------------------------
|
|
# WebSocket
|
|
# ---------------------------------------------------------------------------
|
|
/ws:
|
|
get:
|
|
operationId: connectWebSocket
|
|
tags: [system]
|
|
summary: WebSocket connection for real-time updates
|
|
description: |
|
|
Upgrades to a WebSocket connection that streams execution progress,
|
|
node status, and output messages. The server sends an initial `status`
|
|
message with the session ID (SID) on connect.
|
|
|
|
## Message types (server → client)
|
|
The server sends JSON messages with a `type` field. See the
|
|
`x-websocket-messages` list below for the schema of each message type.
|
|
parameters:
|
|
- name: clientId
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Client identifier. If omitted the server assigns one.
|
|
responses:
|
|
"101":
|
|
description: WebSocket upgrade successful
|
|
x-websocket-messages:
|
|
- type: status
|
|
schema:
|
|
$ref: "#/components/schemas/StatusWsMessage"
|
|
- type: progress
|
|
schema:
|
|
$ref: "#/components/schemas/ProgressWsMessage"
|
|
- type: progress_text
|
|
schema:
|
|
$ref: "#/components/schemas/ProgressTextWsMessage"
|
|
- type: progress_state
|
|
schema:
|
|
$ref: "#/components/schemas/ProgressStateWsMessage"
|
|
- type: executing
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutingWsMessage"
|
|
- type: executed
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutedWsMessage"
|
|
- type: execution_start
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutionStartWsMessage"
|
|
- type: execution_success
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutionSuccessWsMessage"
|
|
- type: execution_cached
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutionCachedWsMessage"
|
|
- type: execution_interrupted
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutionInterruptedWsMessage"
|
|
- type: execution_error
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutionErrorWsMessage"
|
|
- type: logs
|
|
schema:
|
|
$ref: "#/components/schemas/LogsWsMessage"
|
|
- type: notification
|
|
schema:
|
|
$ref: "#/components/schemas/NotificationWsMessage"
|
|
- type: feature_flags
|
|
schema:
|
|
$ref: "#/components/schemas/FeatureFlagsWsMessage"
|
|
- type: asset_download
|
|
schema:
|
|
$ref: "#/components/schemas/AssetDownloadWsMessage"
|
|
- type: asset_export
|
|
schema:
|
|
$ref: "#/components/schemas/AssetExportWsMessage"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Prompt
|
|
# ---------------------------------------------------------------------------
|
|
/api/prompt:
|
|
get:
|
|
operationId: getPromptInfo
|
|
tags: [prompt]
|
|
summary: Get queue status
|
|
description: Returns how many items remain in the execution queue.
|
|
responses:
|
|
"200":
|
|
description: Queue info
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PromptInfo"
|
|
post:
|
|
operationId: executePrompt
|
|
tags: [prompt]
|
|
summary: Submit a workflow for execution
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PromptRequest"
|
|
responses:
|
|
"200":
|
|
description: Prompt accepted
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PromptResponse"
|
|
"400":
|
|
description: Validation or node errors
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PromptErrorResponse"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Queue
|
|
# ---------------------------------------------------------------------------
|
|
/api/queue:
|
|
get:
|
|
operationId: getQueue
|
|
tags: [queue]
|
|
summary: Get running and pending queue items
|
|
responses:
|
|
"200":
|
|
description: Queue contents
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/QueueInfo"
|
|
post:
|
|
operationId: manageQueue
|
|
tags: [queue]
|
|
summary: Clear or delete items from the queue
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/QueueManageRequest"
|
|
responses:
|
|
"200":
|
|
description: Queue updated
|
|
|
|
/api/interrupt:
|
|
post:
|
|
operationId: interruptExecution
|
|
tags: [queue]
|
|
summary: Interrupt current execution
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
prompt_id:
|
|
type: string
|
|
format: uuid
|
|
description: "If provided, only interrupts this specific running prompt. Otherwise interrupts all."
|
|
responses:
|
|
"200":
|
|
description: Interrupt signal sent
|
|
|
|
/api/free:
|
|
post:
|
|
operationId: freeMemory
|
|
tags: [queue]
|
|
summary: Free GPU memory and/or unload models
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
unload_models:
|
|
type: boolean
|
|
description: Unload all models from VRAM/RAM
|
|
free_memory:
|
|
type: boolean
|
|
description: Run garbage collection and free cached memory
|
|
responses:
|
|
"200":
|
|
description: Memory freed
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Jobs
|
|
# ---------------------------------------------------------------------------
|
|
/api/jobs:
|
|
get:
|
|
operationId: listJobs
|
|
tags: [queue]
|
|
summary: List jobs with filtering and pagination
|
|
parameters:
|
|
- name: status
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Filter by job status
|
|
- name: workflow_id
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Filter by workflow ID
|
|
- name: sort_by
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Field to sort by
|
|
- name: sort_order
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum: [asc, desc]
|
|
description: Sort direction
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
description: Maximum number of results (default is unlimited/None)
|
|
- name: offset
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
description: Pagination offset
|
|
responses:
|
|
"200":
|
|
description: Jobs list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
jobs:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/JobEntry"
|
|
pagination:
|
|
$ref: "#/components/schemas/PaginationInfo"
|
|
|
|
/api/jobs/{job_id}:
|
|
get:
|
|
operationId: getJob
|
|
tags: [queue]
|
|
summary: Get a single job by ID
|
|
parameters:
|
|
- name: job_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
"200":
|
|
description: Job detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/JobDetailResponse"
|
|
"404":
|
|
description: Job not found
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# History
|
|
# ---------------------------------------------------------------------------
|
|
/api/history:
|
|
get:
|
|
operationId: getHistory
|
|
tags: [history]
|
|
summary: Get execution history
|
|
description: |
|
|
Returns a dictionary keyed by prompt_id. Each value is a HistoryEntry
|
|
containing prompt metadata, outputs, status, and node meta.
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
- name: max_items
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
description: Maximum number of history entries to return
|
|
- name: offset
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
description: Pagination offset (number of entries to skip)
|
|
responses:
|
|
"200":
|
|
description: History dictionary keyed by prompt_id
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/HistoryEntry"
|
|
post:
|
|
operationId: manageHistory
|
|
tags: [history]
|
|
summary: Clear or delete history entries
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/HistoryManageRequest"
|
|
responses:
|
|
"200":
|
|
description: History updated
|
|
|
|
/api/history/{prompt_id}:
|
|
get:
|
|
operationId: getHistoryByPromptId
|
|
tags: [history]
|
|
summary: Get history for a specific prompt
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
- name: prompt_id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
"200":
|
|
description: Single-entry history dictionary. Returns an empty object `{}` if the prompt_id is not found.
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/HistoryEntry"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Upload
|
|
# ---------------------------------------------------------------------------
|
|
/api/upload/image:
|
|
post:
|
|
operationId: uploadImage
|
|
tags: [upload]
|
|
summary: Upload an image file
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- image
|
|
properties:
|
|
image:
|
|
type: string
|
|
format: binary
|
|
description: Image file to upload
|
|
type:
|
|
type: string
|
|
enum: [input, temp, output]
|
|
default: input
|
|
description: Target directory type
|
|
overwrite:
|
|
type: string
|
|
description: 'Set to "true" to overwrite existing files'
|
|
subfolder:
|
|
type: string
|
|
description: Subfolder within the target directory
|
|
responses:
|
|
"200":
|
|
description: Upload result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UploadResult"
|
|
"400":
|
|
description: No file provided or invalid request
|
|
|
|
/api/upload/mask:
|
|
post:
|
|
operationId: uploadMask
|
|
tags: [upload]
|
|
summary: Upload a mask image
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- image
|
|
- original_ref
|
|
properties:
|
|
image:
|
|
type: string
|
|
format: binary
|
|
description: Mask image (alpha channel is used)
|
|
original_ref:
|
|
type: object
|
|
description: Reference to the original image file
|
|
required:
|
|
- filename
|
|
properties:
|
|
filename:
|
|
type: string
|
|
description: Filename of the original image
|
|
additionalProperties: true
|
|
type:
|
|
type: string
|
|
enum: [input, temp, output]
|
|
default: input
|
|
description: Target directory type
|
|
overwrite:
|
|
type: string
|
|
description: 'Set to "true" to overwrite existing files'
|
|
subfolder:
|
|
type: string
|
|
description: Subfolder within the target directory
|
|
responses:
|
|
"200":
|
|
description: Upload result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UploadResult"
|
|
"400":
|
|
description: No file provided or invalid request
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# View
|
|
# ---------------------------------------------------------------------------
|
|
/api/view:
|
|
get:
|
|
operationId: viewFile
|
|
tags: [view]
|
|
summary: View or download a file
|
|
parameters:
|
|
- name: filename
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Name of the file to view
|
|
- name: type
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum: [input, output, temp]
|
|
default: output
|
|
description: Directory type
|
|
- name: subfolder
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Subfolder within the directory
|
|
- name: preview
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Preview format hint (e.g. "webp;90")
|
|
- name: channel
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum: [rgba, rgb, a]
|
|
description: Channel extraction mode
|
|
responses:
|
|
"200":
|
|
description: File content
|
|
content:
|
|
image/*:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
video/*:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
audio/*:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
"404":
|
|
description: File not found
|
|
|
|
/api/view_metadata/{folder_name}:
|
|
get:
|
|
operationId: viewMetadata
|
|
tags: [view]
|
|
summary: Get metadata for a file (e.g. safetensors header)
|
|
parameters:
|
|
- name: folder_name
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Folder type (output, input, temp, etc.)
|
|
- name: filename
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Filename to read metadata from
|
|
responses:
|
|
"200":
|
|
description: File metadata
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
"404":
|
|
description: File or metadata not found
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# System
|
|
# ---------------------------------------------------------------------------
|
|
/api/system_stats:
|
|
get:
|
|
operationId: getSystemStats
|
|
tags: [system]
|
|
summary: Get system statistics
|
|
responses:
|
|
"200":
|
|
description: System stats
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/SystemStatsResponse"
|
|
|
|
/api/features:
|
|
get:
|
|
operationId: getFeatures
|
|
tags: [system]
|
|
summary: Get enabled feature flags
|
|
description: Returns a dictionary of feature flag names to their enabled state.
|
|
responses:
|
|
"200":
|
|
description: Feature flags
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
type: boolean
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Node / Object Info
|
|
# ---------------------------------------------------------------------------
|
|
/api/object_info:
|
|
get:
|
|
operationId: getObjectInfo
|
|
tags: [node]
|
|
summary: Get all node definitions
|
|
description: |
|
|
Returns a dictionary of every registered node class, keyed by class name.
|
|
Each value is a NodeInfo object describing inputs, outputs, category, etc.
|
|
responses:
|
|
"200":
|
|
description: All node definitions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/NodeInfo"
|
|
|
|
/api/object_info/{node_class}:
|
|
get:
|
|
operationId: getObjectInfoByClass
|
|
tags: [node]
|
|
summary: Get a single node definition
|
|
parameters:
|
|
- name: node_class
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Node class name (e.g. "KSampler")
|
|
responses:
|
|
"200":
|
|
description: Single node definition
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/NodeInfo"
|
|
"404":
|
|
description: Node class not found
|
|
|
|
/api/embeddings:
|
|
get:
|
|
operationId: getEmbeddings
|
|
tags: [node]
|
|
summary: List available embedding names
|
|
responses:
|
|
"200":
|
|
description: Embedding names
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Models
|
|
# ---------------------------------------------------------------------------
|
|
/api/models:
|
|
get:
|
|
operationId: getModelTypes
|
|
tags: [model]
|
|
summary: List model folder type names
|
|
description: Returns an array of model type names (e.g. checkpoints, loras, vae).
|
|
responses:
|
|
"200":
|
|
description: Model type names
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
/api/models/{folder}:
|
|
get:
|
|
operationId: getModelsByFolder
|
|
tags: [model]
|
|
summary: List model filenames in a folder
|
|
parameters:
|
|
- name: folder
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Model folder type name
|
|
responses:
|
|
"200":
|
|
description: Model filenames
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
"404":
|
|
description: Unknown folder type
|
|
|
|
/api/experiment/models:
|
|
get:
|
|
operationId: getExperimentModels
|
|
tags: [model]
|
|
summary: List model folders with paths
|
|
description: Returns an array of model folder objects with name and folder paths.
|
|
responses:
|
|
"200":
|
|
description: Model folders
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ModelFolder"
|
|
|
|
/api/experiment/models/{folder}:
|
|
get:
|
|
operationId: getExperimentModelsByFolder
|
|
tags: [model]
|
|
summary: List model files with metadata
|
|
parameters:
|
|
- name: folder
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Model folder type name
|
|
responses:
|
|
"200":
|
|
description: Model files with metadata
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ModelFile"
|
|
"404":
|
|
description: Unknown folder type
|
|
|
|
/api/experiment/models/preview/{folder}/{path_index}/{filename}:
|
|
get:
|
|
operationId: getModelPreview
|
|
tags: [model]
|
|
summary: Get model preview image
|
|
parameters:
|
|
- name: folder
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Model folder type name
|
|
- name: path_index
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: integer
|
|
description: Path index within the folder
|
|
- name: filename
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Model filename
|
|
responses:
|
|
"200":
|
|
description: Preview image (WebP)
|
|
content:
|
|
image/webp:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
"404":
|
|
description: Preview not found
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Users
|
|
# ---------------------------------------------------------------------------
|
|
/api/users:
|
|
get:
|
|
operationId: getUsers
|
|
tags: [user]
|
|
summary: Get user storage info
|
|
description: |
|
|
Returns user storage configuration. In single-user mode returns
|
|
`{"storage": "server", "migrated": true/false}`. In multi-user mode
|
|
returns `{"storage": "server", "users": {"user_id": "user_dir", ...}}`.
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
responses:
|
|
"200":
|
|
description: User info
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
storage:
|
|
type: string
|
|
description: Storage backend type (always "server")
|
|
migrated:
|
|
type: boolean
|
|
description: Whether migration from browser storage is complete (single-user)
|
|
users:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Map of user_id to directory name (multi-user)
|
|
post:
|
|
operationId: createUser
|
|
tags: [user]
|
|
summary: Create a new user (multi-user mode)
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- username
|
|
properties:
|
|
username:
|
|
type: string
|
|
description: Username for the new user
|
|
responses:
|
|
"200":
|
|
description: Created user ID
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: string
|
|
description: The generated user_id
|
|
"400":
|
|
description: Username already exists or invalid
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Userdata
|
|
# ---------------------------------------------------------------------------
|
|
/api/userdata:
|
|
get:
|
|
operationId: listUserdata
|
|
tags: [userdata]
|
|
summary: List files in a userdata directory
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
- name: dir
|
|
in: query
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Directory path relative to the user's data folder
|
|
- name: recurse
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
description: Recurse into subdirectories
|
|
- name: full_info
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
description: Return full file info objects instead of just names
|
|
- name: split
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
description: Split paths into directory components
|
|
responses:
|
|
"200":
|
|
description: File listing
|
|
content:
|
|
application/json:
|
|
schema:
|
|
oneOf:
|
|
- type: array
|
|
items:
|
|
type: string
|
|
description: Simple filename list
|
|
- type: array
|
|
items:
|
|
$ref: "#/components/schemas/GetUserDataResponseFullFile"
|
|
description: Full file info list (when full_info=true)
|
|
"404":
|
|
description: Directory not found
|
|
|
|
/api/v2/userdata:
|
|
get:
|
|
operationId: listUserdataV2
|
|
tags: [userdata]
|
|
summary: List files in userdata (v2 format)
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
- name: path
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Directory path relative to user data root
|
|
responses:
|
|
"200":
|
|
description: File listing with metadata
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
path:
|
|
type: string
|
|
type:
|
|
type: string
|
|
enum: [file, directory]
|
|
size:
|
|
type: integer
|
|
modified:
|
|
type: number
|
|
description: Unix timestamp
|
|
|
|
/api/userdata/{file}:
|
|
get:
|
|
operationId: getUserdataFile
|
|
tags: [userdata]
|
|
summary: Read a userdata file
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
- name: file
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: File path relative to user data directory
|
|
responses:
|
|
"200":
|
|
description: File content
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
"404":
|
|
description: File not found
|
|
post:
|
|
operationId: writeUserdataFile
|
|
tags: [userdata]
|
|
summary: Write or create a userdata file
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
- name: file
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: File path relative to user data directory
|
|
- name: overwrite
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
description: Allow overwriting existing files
|
|
- name: full_info
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
description: Return full file info in response
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
application/json:
|
|
schema: {}
|
|
responses:
|
|
"200":
|
|
description: File written
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UserDataResponse"
|
|
"409":
|
|
description: File exists and overwrite not set
|
|
delete:
|
|
operationId: deleteUserdataFile
|
|
tags: [userdata]
|
|
summary: Delete a userdata file
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
- name: file
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: File path relative to user data directory
|
|
responses:
|
|
"204":
|
|
description: File deleted
|
|
"404":
|
|
description: File not found
|
|
|
|
/api/userdata/{file}/move/{dest}:
|
|
post:
|
|
operationId: moveUserdataFile
|
|
tags: [userdata]
|
|
summary: Move or rename a userdata file
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
- name: file
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Source file path
|
|
- name: dest
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Destination file path
|
|
- name: overwrite
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
description: Allow overwriting at destination
|
|
- name: full_info
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
description: Return full file info in response
|
|
responses:
|
|
"200":
|
|
description: File moved
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/UserDataResponse"
|
|
"404":
|
|
description: Source file not found
|
|
"409":
|
|
description: Destination exists and overwrite not set
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Settings
|
|
# ---------------------------------------------------------------------------
|
|
/api/settings:
|
|
get:
|
|
operationId: getSettings
|
|
tags: [settings]
|
|
summary: Get all user settings
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
responses:
|
|
"200":
|
|
description: Settings object
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
post:
|
|
operationId: updateSettings
|
|
tags: [settings]
|
|
summary: Update user settings (partial merge)
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Partial settings to merge
|
|
responses:
|
|
"200":
|
|
description: Settings updated
|
|
|
|
/api/settings/{id}:
|
|
get:
|
|
operationId: getSetting
|
|
tags: [settings]
|
|
summary: Get a single setting by key
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Setting key
|
|
responses:
|
|
"200":
|
|
description: Setting value (null if the setting does not exist)
|
|
content:
|
|
application/json:
|
|
schema:
|
|
nullable: true
|
|
description: The setting value (any JSON type), or null if not set
|
|
post:
|
|
operationId: updateSetting
|
|
tags: [settings]
|
|
summary: Set a single setting value
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Setting key
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
description: The setting value (any JSON type)
|
|
responses:
|
|
"200":
|
|
description: Setting updated
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Extensions / Templates / i18n
|
|
# ---------------------------------------------------------------------------
|
|
/api/extensions:
|
|
get:
|
|
operationId: getExtensions
|
|
tags: [extensions]
|
|
summary: List frontend extension JS file paths
|
|
responses:
|
|
"200":
|
|
description: Array of JS file paths
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Relative path to extension JS file
|
|
|
|
/api/workflow_templates:
|
|
get:
|
|
operationId: getWorkflowTemplates
|
|
tags: [extensions]
|
|
summary: Get workflow template mappings
|
|
description: Returns a map of custom node names to their provided workflow template names.
|
|
responses:
|
|
"200":
|
|
description: Template mappings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Map of node pack name to array of template names
|
|
|
|
/api/i18n:
|
|
get:
|
|
operationId: getI18n
|
|
tags: [extensions]
|
|
summary: Get internationalisation translation strings
|
|
responses:
|
|
"200":
|
|
description: Translation map
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Nested map of locale to translation key-value pairs
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Subgraphs
|
|
# ---------------------------------------------------------------------------
|
|
/api/global_subgraphs:
|
|
get:
|
|
operationId: getGlobalSubgraphs
|
|
tags: [subgraph]
|
|
summary: List global subgraph blueprints
|
|
description: Returns a dictionary of subgraph IDs to their metadata.
|
|
responses:
|
|
"200":
|
|
description: Subgraph metadata dictionary
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/GlobalSubgraphInfo"
|
|
|
|
/api/global_subgraphs/{id}:
|
|
get:
|
|
operationId: getGlobalSubgraph
|
|
tags: [subgraph]
|
|
summary: Get a global subgraph with full data
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Subgraph identifier
|
|
responses:
|
|
"200":
|
|
description: Full subgraph data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/GlobalSubgraphData"
|
|
"404":
|
|
description: Subgraph not found
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Node Replacements
|
|
# ---------------------------------------------------------------------------
|
|
/api/node_replacements:
|
|
get:
|
|
operationId: getNodeReplacements
|
|
tags: [node]
|
|
summary: Get node replacement mappings
|
|
description: |
|
|
Returns a dictionary mapping deprecated or replaced node class names
|
|
to their replacement node information.
|
|
responses:
|
|
"200":
|
|
description: Replacement mappings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Internal (x-internal: true)
|
|
# ---------------------------------------------------------------------------
|
|
/internal/logs:
|
|
get:
|
|
operationId: getInternalLogs
|
|
tags: [internal]
|
|
summary: Get server logs as text
|
|
x-internal: true
|
|
responses:
|
|
"200":
|
|
description: Log text
|
|
content:
|
|
text/plain:
|
|
schema:
|
|
type: string
|
|
|
|
/internal/logs/raw:
|
|
get:
|
|
operationId: getInternalLogsRaw
|
|
tags: [internal]
|
|
summary: Get raw structured log entries
|
|
x-internal: true
|
|
responses:
|
|
"200":
|
|
description: Structured log data
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
entries:
|
|
type: array
|
|
items:
|
|
type: object
|
|
properties:
|
|
t:
|
|
type: number
|
|
description: Timestamp
|
|
m:
|
|
type: string
|
|
description: Message
|
|
size:
|
|
type: object
|
|
properties:
|
|
cols:
|
|
type: integer
|
|
rows:
|
|
type: integer
|
|
|
|
/internal/logs/subscribe:
|
|
patch:
|
|
operationId: subscribeToLogs
|
|
tags: [internal]
|
|
summary: Subscribe or unsubscribe a WebSocket client to log streaming
|
|
x-internal: true
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- clientId
|
|
- enabled
|
|
properties:
|
|
clientId:
|
|
type: string
|
|
description: WebSocket client ID
|
|
enabled:
|
|
type: boolean
|
|
description: Enable or disable log streaming for this client
|
|
responses:
|
|
"200":
|
|
description: Subscription updated
|
|
|
|
/internal/folder_paths:
|
|
get:
|
|
operationId: getInternalFolderPaths
|
|
tags: [internal]
|
|
summary: Get configured folder paths
|
|
x-internal: true
|
|
responses:
|
|
"200":
|
|
description: Dictionary of folder type to paths
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
type: array
|
|
items:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Map of folder type name to list of [path, ...] entries
|
|
|
|
/internal/files/{directory_type}:
|
|
get:
|
|
operationId: getInternalFiles
|
|
tags: [internal]
|
|
summary: List files in a directory type
|
|
x-internal: true
|
|
parameters:
|
|
- name: directory_type
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Directory type (e.g. output, input, temp)
|
|
responses:
|
|
"200":
|
|
description: Array of filenames
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Assets (x-feature-gate: enable-assets)
|
|
# ---------------------------------------------------------------------------
|
|
/api/assets/hash/{hash}:
|
|
head:
|
|
operationId: checkAssetByHash
|
|
tags: [assets]
|
|
summary: Check if an asset with the given hash exists
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: hash
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: "Blake3 hash of the asset (e.g. blake3:abc123...)"
|
|
responses:
|
|
"200":
|
|
description: Asset exists
|
|
"404":
|
|
description: No asset with this hash
|
|
|
|
/api/assets:
|
|
get:
|
|
operationId: listAssets
|
|
tags: [assets]
|
|
summary: List assets with filtering and pagination
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 50
|
|
- name: offset
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
default: 0
|
|
- name: include_tags
|
|
in: query
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
style: form
|
|
explode: true
|
|
description: Tags that assets must have (AND logic)
|
|
- name: exclude_tags
|
|
in: query
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
style: form
|
|
explode: true
|
|
description: Tags that assets must not have
|
|
- name: name_contains
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Filter assets whose name contains this substring
|
|
- name: metadata_filter
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: JSON-encoded metadata key/value filter
|
|
- name: sort
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Field to sort by
|
|
- name: order
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum: [asc, desc]
|
|
description: Sort direction
|
|
responses:
|
|
"200":
|
|
description: Asset list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ListAssetsResponse"
|
|
post:
|
|
operationId: createAsset
|
|
tags: [assets]
|
|
summary: Upload a new asset
|
|
x-feature-gate: enable-assets
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
multipart/form-data:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- file
|
|
properties:
|
|
file:
|
|
type: string
|
|
format: binary
|
|
description: Asset file to upload
|
|
name:
|
|
type: string
|
|
description: Display name for the asset
|
|
tags:
|
|
type: string
|
|
description: Comma-separated tags
|
|
user_metadata:
|
|
type: string
|
|
description: JSON-encoded user metadata
|
|
hash:
|
|
type: string
|
|
description: "Blake3 hash of the file content (e.g. blake3:abc123...)"
|
|
mime_type:
|
|
type: string
|
|
description: MIME type of the file (overrides auto-detected type)
|
|
preview_id:
|
|
type: string
|
|
format: uuid
|
|
description: ID of an existing asset to use as the preview image
|
|
responses:
|
|
"201":
|
|
description: Asset created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AssetCreated"
|
|
|
|
/api/assets/from-hash:
|
|
post:
|
|
operationId: createAssetFromHash
|
|
tags: [assets]
|
|
summary: Create an asset reference from an existing hash
|
|
x-feature-gate: enable-assets
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- hash
|
|
- name
|
|
properties:
|
|
hash:
|
|
type: string
|
|
description: Blake3 hash of existing content
|
|
name:
|
|
type: string
|
|
description: Display name
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
user_metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
responses:
|
|
"201":
|
|
description: Asset created from hash
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AssetCreated"
|
|
|
|
/api/assets/{id}:
|
|
get:
|
|
operationId: getAsset
|
|
tags: [assets]
|
|
summary: Get asset metadata
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
"200":
|
|
description: Asset metadata
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Asset"
|
|
"404":
|
|
description: Asset not found
|
|
put:
|
|
operationId: updateAsset
|
|
tags: [assets]
|
|
summary: Update asset metadata
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: New display name for the asset
|
|
user_metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Custom user metadata to set
|
|
preview_id:
|
|
type: string
|
|
format: uuid
|
|
description: ID of the asset to use as the preview
|
|
responses:
|
|
"200":
|
|
description: Asset updated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AssetUpdated"
|
|
delete:
|
|
operationId: deleteAsset
|
|
tags: [assets]
|
|
summary: Delete an asset
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
- name: delete_content
|
|
in: query
|
|
schema:
|
|
type: boolean
|
|
description: Also delete the underlying content file
|
|
responses:
|
|
"204":
|
|
description: Asset deleted
|
|
|
|
/api/assets/{id}/content:
|
|
get:
|
|
operationId: getAssetContent
|
|
tags: [assets]
|
|
summary: Download asset file content
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
"200":
|
|
description: Asset file content
|
|
content:
|
|
application/octet-stream:
|
|
schema:
|
|
type: string
|
|
format: binary
|
|
"404":
|
|
description: Asset not found
|
|
|
|
/api/assets/{id}/tags:
|
|
post:
|
|
operationId: addAssetTags
|
|
tags: [assets]
|
|
summary: Add tags to an asset
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- tags
|
|
properties:
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Tags added
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TagsModificationResponse"
|
|
delete:
|
|
operationId: removeAssetTags
|
|
tags: [assets]
|
|
summary: Remove tags from an asset
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- tags
|
|
properties:
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
responses:
|
|
"200":
|
|
description: Tags removed
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/TagsModificationResponse"
|
|
|
|
/api/tags:
|
|
get:
|
|
operationId: listTags
|
|
tags: [assets]
|
|
summary: List all known tags with counts
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
- name: offset
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
- name: search
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Search term for tag name
|
|
responses:
|
|
"200":
|
|
description: Tag list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/ListTagsResponse"
|
|
|
|
/api/assets/tags/refine:
|
|
get:
|
|
operationId: refineAssetTags
|
|
tags: [assets]
|
|
summary: Get tag counts for assets matching current filters
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: include_tags
|
|
in: query
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
style: form
|
|
explode: true
|
|
description: Tags that assets must have (AND logic)
|
|
- name: exclude_tags
|
|
in: query
|
|
schema:
|
|
type: array
|
|
items:
|
|
type: string
|
|
style: form
|
|
explode: true
|
|
description: Tags that assets must not have
|
|
- name: name_contains
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Filter assets whose name contains this substring
|
|
- name: metadata_filter
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: JSON-encoded metadata key/value filter
|
|
- name: limit
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
- name: offset
|
|
in: query
|
|
schema:
|
|
type: integer
|
|
- name: sort
|
|
in: query
|
|
schema:
|
|
type: string
|
|
description: Field to sort by
|
|
- name: order
|
|
in: query
|
|
schema:
|
|
type: string
|
|
enum: [asc, desc]
|
|
description: Sort direction
|
|
responses:
|
|
"200":
|
|
description: Tag histogram
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AssetTagHistogramResponse"
|
|
|
|
/api/assets/seed:
|
|
post:
|
|
operationId: seedAssets
|
|
tags: [assets]
|
|
summary: Trigger asset scan/seed from filesystem
|
|
x-feature-gate: enable-assets
|
|
requestBody:
|
|
required: false
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
roots:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Root folder paths to scan (if omitted, scans all)
|
|
responses:
|
|
"200":
|
|
description: Seed started
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
|
|
/api/assets/seed/status:
|
|
get:
|
|
operationId: getAssetSeedStatus
|
|
tags: [assets]
|
|
summary: Get asset scan progress
|
|
x-feature-gate: enable-assets
|
|
responses:
|
|
"200":
|
|
description: Scan progress
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Scan progress details (files scanned, total, status, etc.)
|
|
|
|
/api/assets/seed/cancel:
|
|
post:
|
|
operationId: cancelAssetSeed
|
|
tags: [assets]
|
|
summary: Cancel an in-progress asset scan
|
|
x-feature-gate: enable-assets
|
|
responses:
|
|
"200":
|
|
description: Scan cancelled
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
|
|
/api/assets/prune:
|
|
post:
|
|
operationId: pruneAssets
|
|
tags: [assets]
|
|
summary: Mark assets whose backing files no longer exist on disk
|
|
x-feature-gate: enable-assets
|
|
responses:
|
|
"200":
|
|
description: Prune result
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
status:
|
|
type: string
|
|
marked:
|
|
type: integer
|
|
description: Number of assets marked as missing
|
|
|
|
components:
|
|
parameters:
|
|
ComfyUserHeader:
|
|
name: Comfy-User
|
|
in: header
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: |
|
|
Identifies the active user in multi-user mode. Used for settings,
|
|
userdata, and history isolation. This is not a security mechanism —
|
|
it is an organisational convenience with no authentication behind it.
|
|
|
|
schemas:
|
|
# -------------------------------------------------------------------
|
|
# Prompt
|
|
# -------------------------------------------------------------------
|
|
PromptRequest:
|
|
type: object
|
|
required:
|
|
- prompt
|
|
properties:
|
|
prompt:
|
|
type: object
|
|
description: |
|
|
The workflow graph to execute. Keys are node IDs (strings);
|
|
values are objects with class_type and inputs.
|
|
additionalProperties: true
|
|
number:
|
|
type: number
|
|
description: Priority number for the queue (lower numbers have higher priority)
|
|
front:
|
|
type: boolean
|
|
description: If true, adds the prompt to the front of the queue
|
|
extra_data:
|
|
type: object
|
|
description: Extra data associated with the prompt (e.g. extra_pnginfo)
|
|
additionalProperties: true
|
|
client_id:
|
|
type: string
|
|
description: WebSocket client ID to receive progress updates
|
|
prompt_id:
|
|
type: string
|
|
format: uuid
|
|
description: "Client-supplied prompt ID. Server generates a UUID if omitted."
|
|
partial_execution_targets:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: List of node IDs to execute (partial graph execution)
|
|
|
|
PromptResponse:
|
|
type: object
|
|
properties:
|
|
prompt_id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique identifier for the prompt execution
|
|
number:
|
|
type: number
|
|
description: Priority number in the queue
|
|
node_errors:
|
|
type: object
|
|
description: Validation errors keyed by node ID
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/NodeError"
|
|
error:
|
|
description: Top-level prompt error (string message or structured error)
|
|
oneOf:
|
|
- type: string
|
|
- $ref: "#/components/schemas/PromptError"
|
|
|
|
PromptErrorResponse:
|
|
type: object
|
|
description: Error response when prompt validation fails
|
|
additionalProperties: true
|
|
|
|
PromptError:
|
|
type: object
|
|
description: Structured prompt validation error
|
|
properties:
|
|
type:
|
|
type: string
|
|
message:
|
|
type: string
|
|
details:
|
|
type: string
|
|
|
|
Error:
|
|
type: object
|
|
description: Detailed node-level error
|
|
properties:
|
|
type:
|
|
type: string
|
|
message:
|
|
type: string
|
|
details:
|
|
type: string
|
|
extra_info:
|
|
type: object
|
|
properties:
|
|
input_name:
|
|
type: string
|
|
additionalProperties: true
|
|
|
|
NodeError:
|
|
type: object
|
|
description: Error details for a single node
|
|
properties:
|
|
errors:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Error"
|
|
class_type:
|
|
type: string
|
|
description: The node's class type
|
|
dependent_outputs:
|
|
type: array
|
|
items: {}
|
|
|
|
PromptInfo:
|
|
type: object
|
|
properties:
|
|
exec_info:
|
|
type: object
|
|
properties:
|
|
queue_remaining:
|
|
type: integer
|
|
description: Number of items remaining in the queue
|
|
|
|
# -------------------------------------------------------------------
|
|
# Queue
|
|
# -------------------------------------------------------------------
|
|
QueueInfo:
|
|
type: object
|
|
description: Queue information with pending and running items
|
|
properties:
|
|
queue_running:
|
|
type: array
|
|
description: Currently running queue items
|
|
items:
|
|
type: array
|
|
description: |
|
|
Queue item tuple: [number, prompt_id, prompt, extra_data, outputs_to_execute, sensitive]
|
|
items: {}
|
|
prefixItems:
|
|
- type: number
|
|
description: Priority number
|
|
- type: string
|
|
format: uuid
|
|
description: prompt_id
|
|
- type: object
|
|
description: prompt graph
|
|
additionalProperties: true
|
|
- type: object
|
|
description: extra_data
|
|
additionalProperties: true
|
|
- type: array
|
|
description: outputs_to_execute (list of output node IDs)
|
|
items:
|
|
type: string
|
|
- type: object
|
|
description: sensitive data (may be omitted)
|
|
additionalProperties: true
|
|
queue_pending:
|
|
type: array
|
|
description: Pending queue items (oldest first)
|
|
items:
|
|
type: array
|
|
description: |
|
|
Queue item tuple: [number, prompt_id, prompt, extra_data, outputs_to_execute, sensitive]
|
|
items: {}
|
|
prefixItems:
|
|
- type: number
|
|
description: Priority number
|
|
- type: string
|
|
format: uuid
|
|
description: prompt_id
|
|
- type: object
|
|
description: prompt graph
|
|
additionalProperties: true
|
|
- type: object
|
|
description: extra_data
|
|
additionalProperties: true
|
|
- type: array
|
|
description: outputs_to_execute (list of output node IDs)
|
|
items:
|
|
type: string
|
|
- type: object
|
|
description: sensitive data (may be omitted)
|
|
additionalProperties: true
|
|
|
|
QueueManageRequest:
|
|
type: object
|
|
description: Request to clear or delete from queue
|
|
properties:
|
|
clear:
|
|
type: boolean
|
|
description: If true, clear all pending items
|
|
delete:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of prompt IDs to delete from queue
|
|
|
|
# -------------------------------------------------------------------
|
|
# History
|
|
# -------------------------------------------------------------------
|
|
HistoryEntry:
|
|
type: object
|
|
description: A single execution history entry
|
|
properties:
|
|
prompt:
|
|
type: array
|
|
description: |
|
|
Prompt tuple: [number, prompt_id, prompt_graph, extra_data, output_node_ids]
|
|
items: {}
|
|
outputs:
|
|
type: object
|
|
description: Output data from execution keyed by node ID
|
|
additionalProperties: true
|
|
status:
|
|
type: object
|
|
description: Execution status (status_str, completed, messages, etc.)
|
|
additionalProperties: true
|
|
meta:
|
|
type: object
|
|
description: Metadata about the execution and nodes
|
|
additionalProperties: true
|
|
|
|
HistoryManageRequest:
|
|
type: object
|
|
description: Request to clear or delete history entries
|
|
properties:
|
|
clear:
|
|
type: boolean
|
|
description: If true, clear all history
|
|
delete:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of prompt IDs to delete from history
|
|
|
|
# -------------------------------------------------------------------
|
|
# Jobs
|
|
# -------------------------------------------------------------------
|
|
JobEntry:
|
|
type: object
|
|
description: Lightweight job data for list views
|
|
required:
|
|
- id
|
|
- status
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique job identifier (same as prompt_id)
|
|
status:
|
|
type: string
|
|
description: Current job status
|
|
create_time:
|
|
type: number
|
|
description: Job creation timestamp
|
|
execution_start_time:
|
|
type: number
|
|
description: Workflow execution start timestamp
|
|
execution_end_time:
|
|
type: number
|
|
description: Workflow execution end timestamp
|
|
preview_output:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Primary preview output
|
|
outputs_count:
|
|
type: integer
|
|
description: Total number of output files
|
|
|
|
JobDetailResponse:
|
|
type: object
|
|
description: Full job details including workflow and outputs
|
|
required:
|
|
- id
|
|
- status
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
status:
|
|
type: string
|
|
workflow:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Full ComfyUI workflow
|
|
outputs:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Full outputs object from execution
|
|
execution_error:
|
|
$ref: "#/components/schemas/ExecutionError"
|
|
create_time:
|
|
type: number
|
|
update_time:
|
|
type: number
|
|
execution_start_time:
|
|
type: number
|
|
execution_end_time:
|
|
type: number
|
|
preview_output:
|
|
type: object
|
|
additionalProperties: true
|
|
outputs_count:
|
|
type: integer
|
|
execution_status:
|
|
type: object
|
|
additionalProperties: true
|
|
execution_meta:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
ExecutionError:
|
|
type: object
|
|
description: Detailed execution error from ComfyUI
|
|
properties:
|
|
node_id:
|
|
type: string
|
|
description: ID of the node that failed
|
|
node_type:
|
|
type: string
|
|
description: Type name of the node
|
|
exception_message:
|
|
type: string
|
|
description: Human-readable error message
|
|
exception_type:
|
|
type: string
|
|
description: Python exception type
|
|
traceback:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Traceback lines
|
|
current_inputs:
|
|
type: object
|
|
additionalProperties: true
|
|
current_outputs:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
PaginationInfo:
|
|
type: object
|
|
properties:
|
|
offset:
|
|
type: integer
|
|
limit:
|
|
type: integer
|
|
total:
|
|
type: integer
|
|
has_more:
|
|
type: boolean
|
|
|
|
# -------------------------------------------------------------------
|
|
# Upload / View
|
|
# -------------------------------------------------------------------
|
|
UploadResult:
|
|
type: object
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Saved filename (may be renamed to avoid collisions)
|
|
subfolder:
|
|
type: string
|
|
description: Subfolder the file was saved to
|
|
type:
|
|
type: string
|
|
description: Directory type (input, temp)
|
|
|
|
# -------------------------------------------------------------------
|
|
# System
|
|
# -------------------------------------------------------------------
|
|
DeviceStats:
|
|
type: object
|
|
description: GPU/compute device statistics
|
|
required:
|
|
- name
|
|
- type
|
|
- index
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Device name
|
|
type:
|
|
type: string
|
|
description: Device type (cuda, mps, cpu, etc.)
|
|
index:
|
|
type: number
|
|
description: Device index
|
|
vram_total:
|
|
type: number
|
|
description: Total VRAM in bytes
|
|
vram_free:
|
|
type: number
|
|
description: Free VRAM in bytes
|
|
torch_vram_total:
|
|
type: number
|
|
description: Total PyTorch-managed VRAM in bytes
|
|
torch_vram_free:
|
|
type: number
|
|
description: Free PyTorch-managed VRAM in bytes
|
|
|
|
SystemStatsResponse:
|
|
type: object
|
|
required:
|
|
- system
|
|
- devices
|
|
properties:
|
|
system:
|
|
type: object
|
|
required:
|
|
- os
|
|
- python_version
|
|
- embedded_python
|
|
- comfyui_version
|
|
- pytorch_version
|
|
- argv
|
|
- ram_total
|
|
- ram_free
|
|
properties:
|
|
os:
|
|
type: string
|
|
description: Operating system
|
|
python_version:
|
|
type: string
|
|
description: Python version
|
|
embedded_python:
|
|
type: boolean
|
|
description: Whether using embedded Python
|
|
comfyui_version:
|
|
type: string
|
|
description: ComfyUI version string
|
|
pytorch_version:
|
|
type: string
|
|
description: PyTorch version
|
|
required_frontend_version:
|
|
type: string
|
|
description: Required frontend version
|
|
argv:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Command line arguments
|
|
ram_total:
|
|
type: number
|
|
description: Total RAM in bytes
|
|
ram_free:
|
|
type: number
|
|
description: Free RAM in bytes
|
|
installed_templates_version:
|
|
type: string
|
|
nullable: true
|
|
description: Version of the currently installed workflow templates
|
|
required_templates_version:
|
|
type: string
|
|
nullable: true
|
|
description: Minimum required workflow templates version for this ComfyUI build
|
|
devices:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/DeviceStats"
|
|
|
|
# -------------------------------------------------------------------
|
|
# Node / Object Info
|
|
# -------------------------------------------------------------------
|
|
NodeInfo:
|
|
type: object
|
|
properties:
|
|
input:
|
|
type: object
|
|
description: Input specifications (required and optional groups)
|
|
additionalProperties: true
|
|
input_order:
|
|
type: object
|
|
description: Ordered input names per group
|
|
additionalProperties:
|
|
type: array
|
|
items:
|
|
type: string
|
|
output:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Output type names
|
|
output_is_list:
|
|
type: array
|
|
items:
|
|
type: boolean
|
|
description: Whether each output is a list
|
|
output_name:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Display names of outputs
|
|
name:
|
|
type: string
|
|
description: Internal class name
|
|
display_name:
|
|
type: string
|
|
description: Human-readable display name
|
|
description:
|
|
type: string
|
|
description: Node description
|
|
python_module:
|
|
type: string
|
|
description: Python module implementing the node
|
|
category:
|
|
type: string
|
|
description: Node category path
|
|
output_node:
|
|
type: boolean
|
|
description: Whether this is an output node
|
|
output_tooltips:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Tooltips for each output
|
|
deprecated:
|
|
type: boolean
|
|
description: Whether the node is deprecated
|
|
experimental:
|
|
type: boolean
|
|
description: Whether the node is experimental
|
|
api_node:
|
|
type: boolean
|
|
description: Whether this is an API node
|
|
is_input_list:
|
|
type: boolean
|
|
description: Whether the node accepts list inputs
|
|
dev_only:
|
|
type: boolean
|
|
description: Whether the node is developer-only (hidden in production UI)
|
|
has_intermediate_output:
|
|
type: boolean
|
|
description: Whether the node emits intermediate output during execution
|
|
search_aliases:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Alternative search terms for finding this node
|
|
essentials_category:
|
|
type: string
|
|
description: Category override used by the essentials pack
|
|
|
|
# -------------------------------------------------------------------
|
|
# Models
|
|
# -------------------------------------------------------------------
|
|
ModelFolder:
|
|
type: object
|
|
required:
|
|
- name
|
|
- folders
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Model folder type name (e.g. "checkpoints")
|
|
folders:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Filesystem paths for this model type
|
|
|
|
ModelFile:
|
|
type: object
|
|
required:
|
|
- name
|
|
- pathIndex
|
|
properties:
|
|
name:
|
|
type: string
|
|
description: Model filename
|
|
pathIndex:
|
|
type: integer
|
|
description: Index into the folder's paths array
|
|
modified:
|
|
type: number
|
|
description: File modification timestamp
|
|
created:
|
|
type: number
|
|
description: File creation timestamp
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
description: File size in bytes
|
|
|
|
# -------------------------------------------------------------------
|
|
# Subgraphs
|
|
# -------------------------------------------------------------------
|
|
GlobalSubgraphInfo:
|
|
type: object
|
|
description: Metadata for a global subgraph blueprint (without full data)
|
|
required:
|
|
- source
|
|
- name
|
|
- info
|
|
properties:
|
|
source:
|
|
type: string
|
|
description: Source type ("templates" or "custom_node")
|
|
name:
|
|
type: string
|
|
description: Display name of the subgraph blueprint
|
|
info:
|
|
type: object
|
|
description: Additional information about the subgraph
|
|
required:
|
|
- node_pack
|
|
properties:
|
|
node_pack:
|
|
type: string
|
|
description: The node pack/module providing this subgraph
|
|
data:
|
|
type: string
|
|
description: The full subgraph JSON data (may be empty in list view)
|
|
|
|
GlobalSubgraphData:
|
|
type: object
|
|
description: Full data for a global subgraph blueprint
|
|
required:
|
|
- source
|
|
- name
|
|
- info
|
|
- data
|
|
properties:
|
|
source:
|
|
type: string
|
|
description: Source type ("templates" or "custom_node")
|
|
name:
|
|
type: string
|
|
description: Display name of the subgraph blueprint
|
|
info:
|
|
type: object
|
|
description: Additional information about the subgraph
|
|
required:
|
|
- node_pack
|
|
properties:
|
|
node_pack:
|
|
type: string
|
|
description: The node pack/module providing this subgraph
|
|
data:
|
|
type: string
|
|
description: The full subgraph JSON data as a string
|
|
|
|
# -------------------------------------------------------------------
|
|
# Userdata
|
|
# -------------------------------------------------------------------
|
|
UserDataResponse:
|
|
oneOf:
|
|
- $ref: "#/components/schemas/UserDataResponseFull"
|
|
- $ref: "#/components/schemas/UserDataResponseShort"
|
|
|
|
UserDataResponseFull:
|
|
type: object
|
|
properties:
|
|
path:
|
|
type: string
|
|
size:
|
|
type: integer
|
|
modified:
|
|
type: integer
|
|
format: int64
|
|
description: Unix timestamp of last modification in milliseconds
|
|
created:
|
|
type: number
|
|
description: Unix timestamp of file creation
|
|
|
|
UserDataResponseShort:
|
|
type: string
|
|
|
|
GetUserDataResponseFullFile:
|
|
type: object
|
|
properties:
|
|
path:
|
|
type: string
|
|
description: File name or path relative to the user directory
|
|
created:
|
|
type: number
|
|
description: Unix timestamp of file creation
|
|
size:
|
|
type: integer
|
|
description: File size in bytes
|
|
modified:
|
|
type: integer
|
|
format: int64
|
|
description: Unix timestamp of last modification in milliseconds
|
|
|
|
# -------------------------------------------------------------------
|
|
# Assets
|
|
# -------------------------------------------------------------------
|
|
Asset:
|
|
type: object
|
|
required:
|
|
- id
|
|
- name
|
|
- size
|
|
- created_at
|
|
- updated_at
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique identifier for the asset
|
|
name:
|
|
type: string
|
|
description: Name of the asset file
|
|
asset_hash:
|
|
type: string
|
|
description: Blake3 hash of the asset content
|
|
pattern: "^blake3:[a-f0-9]{64}$"
|
|
size:
|
|
type: integer
|
|
format: int64
|
|
description: Size of the asset in bytes
|
|
mime_type:
|
|
type: string
|
|
description: MIME type of the asset
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Tags associated with the asset
|
|
user_metadata:
|
|
type: object
|
|
description: Custom user metadata
|
|
additionalProperties: true
|
|
metadata:
|
|
type: object
|
|
description: System-managed metadata (read-only)
|
|
additionalProperties: true
|
|
readOnly: true
|
|
preview_url:
|
|
type: string
|
|
format: uri
|
|
description: URL for asset preview/thumbnail
|
|
preview_id:
|
|
type: string
|
|
format: uuid
|
|
description: ID of the preview asset if available
|
|
prompt_id:
|
|
type: string
|
|
format: uuid
|
|
description: ID of the prompt that created this asset
|
|
created_at:
|
|
type: string
|
|
format: date-time
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
last_access_time:
|
|
type: string
|
|
format: date-time
|
|
is_immutable:
|
|
type: boolean
|
|
description: Whether this asset is immutable
|
|
|
|
AssetCreated:
|
|
allOf:
|
|
- $ref: "#/components/schemas/Asset"
|
|
- type: object
|
|
required:
|
|
- created_new
|
|
properties:
|
|
created_new:
|
|
type: boolean
|
|
description: Whether this was a new creation (true) or returned existing (false)
|
|
|
|
AssetUpdated:
|
|
type: object
|
|
required:
|
|
- id
|
|
- updated_at
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
name:
|
|
type: string
|
|
asset_hash:
|
|
type: string
|
|
pattern: "^blake3:[a-f0-9]{64}$"
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
mime_type:
|
|
type: string
|
|
user_metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
updated_at:
|
|
type: string
|
|
format: date-time
|
|
|
|
ListAssetsResponse:
|
|
type: object
|
|
required:
|
|
- assets
|
|
- total
|
|
- has_more
|
|
properties:
|
|
assets:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/Asset"
|
|
total:
|
|
type: integer
|
|
has_more:
|
|
type: boolean
|
|
|
|
TagInfo:
|
|
type: object
|
|
required:
|
|
- name
|
|
- count
|
|
properties:
|
|
name:
|
|
type: string
|
|
count:
|
|
type: integer
|
|
|
|
ListTagsResponse:
|
|
type: object
|
|
required:
|
|
- tags
|
|
- total
|
|
- has_more
|
|
properties:
|
|
tags:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/TagInfo"
|
|
total:
|
|
type: integer
|
|
has_more:
|
|
type: boolean
|
|
|
|
AssetTagHistogramResponse:
|
|
type: object
|
|
required:
|
|
- tag_counts
|
|
properties:
|
|
tag_counts:
|
|
type: object
|
|
additionalProperties:
|
|
type: integer
|
|
description: Map of tag names to occurrence counts
|
|
|
|
TagsModificationResponse:
|
|
type: object
|
|
required:
|
|
- total_tags
|
|
properties:
|
|
added:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Tags successfully added
|
|
removed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Tags successfully removed
|
|
already_present:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Tags already present (for add)
|
|
not_present:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Tags not present (for remove)
|
|
total_tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: All tags on the asset after the operation
|
|
|
|
# -------------------------------------------------------------------
|
|
# Result / Output types
|
|
# -------------------------------------------------------------------
|
|
ResultItem:
|
|
type: object
|
|
description: A single output file reference
|
|
properties:
|
|
filename:
|
|
type: string
|
|
subfolder:
|
|
type: string
|
|
type:
|
|
type: string
|
|
enum: [input, output, temp]
|
|
display_name:
|
|
type: string
|
|
|
|
NodeOutputs:
|
|
type: object
|
|
description: |
|
|
Outputs from a single node execution. Known keys are listed below,
|
|
but custom nodes may add arbitrary keys (additionalProperties).
|
|
properties:
|
|
images:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ResultItem"
|
|
audio:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ResultItem"
|
|
video:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ResultItem"
|
|
animated:
|
|
type: array
|
|
items:
|
|
type: boolean
|
|
text:
|
|
oneOf:
|
|
- type: string
|
|
- type: array
|
|
items:
|
|
type: string
|
|
additionalProperties: true
|
|
|
|
TaskOutput:
|
|
type: object
|
|
description: Outputs from a full task, keyed by node ID
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/NodeOutputs"
|
|
|
|
# -------------------------------------------------------------------
|
|
# REST response types
|
|
# -------------------------------------------------------------------
|
|
EmbeddingsResponse:
|
|
type: array
|
|
description: List of available embedding names
|
|
items:
|
|
type: string
|
|
|
|
ExtensionsResponse:
|
|
type: array
|
|
description: List of frontend extension JS file URLs
|
|
items:
|
|
type: string
|
|
|
|
TerminalSize:
|
|
type: object
|
|
description: Terminal dimensions
|
|
properties:
|
|
cols:
|
|
type: number
|
|
row:
|
|
type: number
|
|
|
|
LogEntry:
|
|
type: object
|
|
description: A single log entry
|
|
properties:
|
|
t:
|
|
type: string
|
|
description: Timestamp
|
|
m:
|
|
type: string
|
|
description: Log message
|
|
|
|
LogRawResponse:
|
|
type: object
|
|
description: Response from /api/logs/raw
|
|
properties:
|
|
size:
|
|
$ref: "#/components/schemas/TerminalSize"
|
|
entries:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/LogEntry"
|
|
|
|
UserInfo:
|
|
type: object
|
|
description: User mode and storage information
|
|
properties:
|
|
storage:
|
|
type: string
|
|
enum: [server]
|
|
migrated:
|
|
type: boolean
|
|
description: Only present in single-user mode
|
|
users:
|
|
type: object
|
|
description: Only present in multi-user mode — map of user ID to username
|
|
additionalProperties:
|
|
type: string
|
|
|
|
UserDataFullInfo:
|
|
type: object
|
|
description: Full metadata for a userdata file
|
|
properties:
|
|
path:
|
|
type: string
|
|
size:
|
|
type: number
|
|
modified:
|
|
type: number
|
|
description: Unix timestamp of last modification
|
|
created:
|
|
type: number
|
|
description: Unix timestamp of file creation
|
|
|
|
# -------------------------------------------------------------------
|
|
# WebSocket message schemas
|
|
# -------------------------------------------------------------------
|
|
StatusWsMessageStatus:
|
|
type: object
|
|
properties:
|
|
exec_info:
|
|
type: object
|
|
required:
|
|
- queue_remaining
|
|
properties:
|
|
queue_remaining:
|
|
type: integer
|
|
|
|
StatusWsMessage:
|
|
type: object
|
|
description: Initial status message sent on connect + queue status updates
|
|
properties:
|
|
status:
|
|
$ref: "#/components/schemas/StatusWsMessageStatus"
|
|
sid:
|
|
type: string
|
|
description: Session ID assigned by the server
|
|
|
|
ProgressWsMessage:
|
|
type: object
|
|
description: Node execution progress (step N of M)
|
|
required:
|
|
- value
|
|
- max
|
|
- prompt_id
|
|
- node
|
|
properties:
|
|
value:
|
|
type: integer
|
|
description: Current step
|
|
max:
|
|
type: integer
|
|
description: Total steps
|
|
prompt_id:
|
|
type: string
|
|
node:
|
|
type: string
|
|
description: Node ID currently executing
|
|
|
|
ProgressTextWsMessage:
|
|
type: object
|
|
description: Text-based progress update from a node
|
|
properties:
|
|
nodeId:
|
|
type: string
|
|
text:
|
|
type: string
|
|
prompt_id:
|
|
type: string
|
|
|
|
NodeProgressState:
|
|
type: object
|
|
description: Progress state for a single node
|
|
properties:
|
|
value:
|
|
type: number
|
|
max:
|
|
type: number
|
|
state:
|
|
type: string
|
|
enum: [pending, running, finished, error]
|
|
node_id:
|
|
type: string
|
|
prompt_id:
|
|
type: string
|
|
display_node_id:
|
|
type: string
|
|
parent_node_id:
|
|
type: string
|
|
real_node_id:
|
|
type: string
|
|
|
|
ProgressStateWsMessage:
|
|
type: object
|
|
description: Bulk progress state for all nodes in a prompt
|
|
required:
|
|
- prompt_id
|
|
- nodes
|
|
properties:
|
|
prompt_id:
|
|
type: string
|
|
nodes:
|
|
type: object
|
|
description: Map of node ID to progress state
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/NodeProgressState"
|
|
|
|
ExecutingWsMessage:
|
|
type: object
|
|
description: Fired when a node begins execution
|
|
required:
|
|
- node
|
|
- display_node
|
|
- prompt_id
|
|
properties:
|
|
node:
|
|
type: string
|
|
description: Node ID
|
|
display_node:
|
|
type: string
|
|
description: Display node ID (may differ for subgraphs)
|
|
prompt_id:
|
|
type: string
|
|
|
|
ExecutedWsMessage:
|
|
type: object
|
|
description: Fired when a node completes execution with output
|
|
required:
|
|
- node
|
|
- display_node
|
|
- prompt_id
|
|
- output
|
|
properties:
|
|
node:
|
|
type: string
|
|
display_node:
|
|
type: string
|
|
prompt_id:
|
|
type: string
|
|
output:
|
|
$ref: "#/components/schemas/NodeOutputs"
|
|
merge:
|
|
type: boolean
|
|
description: Whether to merge with existing output
|
|
|
|
ExecutionWsMessageBase:
|
|
type: object
|
|
description: Base fields for execution lifecycle messages
|
|
required:
|
|
- prompt_id
|
|
- timestamp
|
|
properties:
|
|
prompt_id:
|
|
type: string
|
|
timestamp:
|
|
type: integer
|
|
description: Unix timestamp in milliseconds
|
|
|
|
ExecutionStartWsMessage:
|
|
allOf:
|
|
- $ref: "#/components/schemas/ExecutionWsMessageBase"
|
|
description: Fired when prompt execution begins
|
|
|
|
ExecutionSuccessWsMessage:
|
|
allOf:
|
|
- $ref: "#/components/schemas/ExecutionWsMessageBase"
|
|
description: Fired when prompt execution completes successfully
|
|
|
|
ExecutionCachedWsMessage:
|
|
allOf:
|
|
- $ref: "#/components/schemas/ExecutionWsMessageBase"
|
|
- type: object
|
|
properties:
|
|
nodes:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: List of node IDs that were cached
|
|
description: Fired when nodes are served from cache
|
|
|
|
ExecutionInterruptedWsMessage:
|
|
allOf:
|
|
- $ref: "#/components/schemas/ExecutionWsMessageBase"
|
|
- type: object
|
|
properties:
|
|
node_id:
|
|
type: string
|
|
node_type:
|
|
type: string
|
|
executed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Node IDs that completed before interruption
|
|
description: Fired when execution is interrupted by user
|
|
|
|
ExecutionErrorWsMessage:
|
|
allOf:
|
|
- $ref: "#/components/schemas/ExecutionWsMessageBase"
|
|
- type: object
|
|
properties:
|
|
node_id:
|
|
type: string
|
|
node_type:
|
|
type: string
|
|
executed:
|
|
type: array
|
|
items:
|
|
type: string
|
|
exception_message:
|
|
type: string
|
|
exception_type:
|
|
type: string
|
|
traceback:
|
|
type: array
|
|
items:
|
|
type: string
|
|
current_inputs: {}
|
|
current_outputs: {}
|
|
description: Fired when a node throws an exception during execution
|
|
|
|
LogsWsMessage:
|
|
type: object
|
|
description: Streaming log entries from the server
|
|
properties:
|
|
size:
|
|
$ref: "#/components/schemas/TerminalSize"
|
|
entries:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/LogEntry"
|
|
|
|
NotificationWsMessage:
|
|
type: object
|
|
description: Server notification (e.g. model download complete)
|
|
properties:
|
|
value:
|
|
type: string
|
|
id:
|
|
type: string
|
|
|
|
FeatureFlagsWsMessage:
|
|
type: object
|
|
description: Feature flags sent on connect
|
|
additionalProperties: true
|
|
|
|
AssetDownloadWsMessage:
|
|
type: object
|
|
description: Asset download progress
|
|
required:
|
|
- task_id
|
|
- asset_name
|
|
- bytes_total
|
|
- bytes_downloaded
|
|
- progress
|
|
- status
|
|
properties:
|
|
task_id:
|
|
type: string
|
|
asset_name:
|
|
type: string
|
|
bytes_total:
|
|
type: number
|
|
bytes_downloaded:
|
|
type: number
|
|
progress:
|
|
type: number
|
|
description: 0.0 to 1.0
|
|
status:
|
|
type: string
|
|
enum: [created, running, completed, failed]
|
|
asset_id:
|
|
type: string
|
|
error:
|
|
type: string
|
|
|
|
AssetExportWsMessage:
|
|
type: object
|
|
description: Bulk asset export progress
|
|
required:
|
|
- task_id
|
|
- assets_total
|
|
- assets_attempted
|
|
- assets_failed
|
|
- bytes_total
|
|
- bytes_processed
|
|
- progress
|
|
- status
|
|
properties:
|
|
task_id:
|
|
type: string
|
|
export_name:
|
|
type: string
|
|
assets_total:
|
|
type: number
|
|
assets_attempted:
|
|
type: number
|
|
assets_failed:
|
|
type: number
|
|
bytes_total:
|
|
type: number
|
|
bytes_processed:
|
|
type: number
|
|
progress:
|
|
type: number
|
|
description: 0.0 to 1.0
|
|
status:
|
|
type: string
|
|
enum: [created, running, completed, failed]
|
|
error:
|
|
type: string
|