The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.
chore(openapi): sync shared API contract from cloud@7c470f0 (#14174)
Comfy Org PR Botbb84c7528313
diff --git a/openapi.yaml b/openapi.yamlindex f801a39d9..b7e21245f 100644--- a/openapi.yaml+++ b/openapi.yaml@@ -1,11749 +1,4956 @@-openapi: 3.1.0-info:- title: ComfyUI API- description: |- API for ComfyUI - A powerful and modular stable diffusion GUI and backend.-- This API allows you to interact with ComfyUI programmatically, including:- - Submitting and managing workflow executions- - Querying node/object information- - Uploading and viewing files- - Managing user settings and data- - Asset management (feature-gated)-- ## Dual-path routing- Every route registered via `self.routes` in the ComfyUI server is available at- both its bare path (e.g. `/prompt`) and an `/api`-prefixed path (e.g. `/api/prompt`).- This spec uses the `/api`-prefixed versions as canonical.-- ## Multi-user mode- When ComfyUI is started with `--multi-user`, the `Comfy-User` header identifies- the active user for settings, userdata, and history isolation. This is **not** a- security mechanism — it is an organisational convenience with no authentication- or authorisation behind it.- version: 1.0.0- license:- name: GNU General Public License v3.0- url: https://github.com/comfyanonymous/ComfyUI/blob/master/LICENSE--servers:- - url: /- description: Default ComfyUI server (typically http://127.0.0.1:8188)--tags:- - name: prompt- description: Workflow submission and prompt info- - name: queue- description: Queue inspection and management- - name: history- description: Execution history- - name: upload- description: File upload endpoints- - name: view- description: File viewing / download- - name: system- description: System stats and feature flags- - name: node- description: Node / object_info definitions- - name: model- description: Model folder and file listing- - name: user- description: User management (multi-user mode)- - name: userdata- description: Per-user file storage- - name: settings- description: Per-user settings- - name: extensions- description: Frontend extension JS files- - name: subgraph- description: Global subgraph blueprints- - name: internal- description: Internal / debug endpoints- - name: assets- description: Asset management (feature-gated behind enable-assets)-- - name: auth- description: Authentication and session management (cloud-only)- - name: billing- description: Billing, subscriptions, and payment management (cloud-only)- - name: workspace- description: Workspace and team management (cloud-only)- - name: hub- description: "ComfyUI Hub: profiles, shared workflows, and labels (cloud-only)"- - name: workflows- description: Cloud workflow management and versioning (cloud-only)- - name: task- description: Background task management (cloud-only)- - name: runtime-only- description: Operations served exclusively by the cloud runtime with no local equivalent--paths:- # ---------------------------------------------------------------------------- # WebSocket- # ---------------------------------------------------------------------------- /ws:- get:- operationId: connectWebSocket- tags: [system]- summary: WebSocket connection for real-time updates- description: |- Upgrades to a WebSocket connection that streams execution progress,- node status, and output messages. The server sends an initial `status`- message with the session ID (SID) on connect.-- ## Message types (server → client)- The server sends JSON messages with a `type` field. See the- `x-websocket-messages` list below for the schema of each message type.- parameters:- - name: clientId- in: query- required: false- schema:- type: string- description: Client identifier. If omitted the server assigns one.- responses:- "101":- description: WebSocket upgrade successful- '401':- description: Unauthorized- 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"- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: executePrompt- tags: [prompt]- summary: Submit a workflow for execution- description: Submits a workflow for execution. The server validates the graph, assigns a `prompt_id`, and enqueues it. Clients listen on `/ws` for execution progress and output messages.- requestBody:- required: true- content:- application/json:- schema:- $ref: "#/components/schemas/PromptRequest"- responses:- "200":- description: Prompt accepted- content:- application/json:- schema:- $ref: "#/components/schemas/PromptResponse"- "400":- description: Validation or node errors- content:- application/json:- schema:- $ref: "#/components/schemas/PromptErrorResponse"-- '402':- description: Payment required - Insufficient credits- content:- application/json:- schema:- $ref: '#/components/schemas/PromptErrorResponse'- '429':- description: Payment required - User has not paid- content:- application/json:- schema:- $ref: '#/components/schemas/PromptErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/PromptErrorResponse'- '503':- description: Service unavailable- content:- application/json:- schema:- $ref: '#/components/schemas/PromptErrorResponse'- # ---------------------------------------------------------------------------- # Queue- # ---------------------------------------------------------------------------- /api/queue:- get:- operationId: getQueueInfo- tags: [queue]- summary: Get running and pending queue items- description: Returns the server's current execution queue, split into the currently-running prompt and the list of pending prompts.- responses:- "200":- description: Queue contents- content:- application/json:- schema:- $ref: "#/components/schemas/QueueInfo"- '400':- description: Invalid request parameters- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Invalid request parameters- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: manageQueue- tags: [queue]- summary: Clear or delete items from the queue- description: Mutates the execution queue. Supports clearing all queued prompts or deleting individual prompts by ID.- requestBody:- required: true- content:- application/json:- schema:- $ref: "#/components/schemas/QueueManageRequest"- responses:- "200":- description: Queue updated- content:- application/json:- schema:- $ref: "#/components/schemas/QueueManageResponse"- '400':- description: Invalid request parameters- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/interrupt:- post:- operationId: interruptJob- tags: [queue]- summary: Interrupt current execution- description: Interrupts the prompt that is currently executing. The next queued prompt (if any) will start immediately after.- requestBody:- required: false- content:- application/json:- schema:- type: object- properties:- prompt_id:- type: string- format: uuid- description: "If provided, only interrupts this specific running prompt. Otherwise interrupts all."- responses:- "200":- description: Interrupt signal sent-- '401':- description: Unauthorized - Authentication required- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/free:- post:- operationId: freeMemory- tags: [queue]- summary: Free GPU memory and/or unload models- description: Frees GPU memory by unloading models and/or freeing the resident model cache, controlled by the request flags.- requestBody:- required: false- content:- application/json:- schema:- type: object- properties:- unload_models:- type: boolean- description: Unload all models from VRAM/RAM- free_memory:- type: boolean- description: Run garbage collection and free cached memory- responses:- "200":- description: Memory freed-- # ---------------------------------------------------------------------------- # Jobs- # ---------------------------------------------------------------------------- /api/jobs:- get:- operationId: listJobs- tags: [queue]- summary: List jobs with filtering and pagination- description: Returns a paginated list of completed prompt executions, newest first.- parameters:- - name: status- in: query- schema:- type: string- description: Filter by job status- - name: workflow_id- in: query- schema:- type: string- description: Filter by workflow ID- - name: sort_by- in: query- schema:- type: string- description: Field to sort by- - name: sort_order- in: query- schema:- type: string- enum: [asc, desc]- description: Sort direction- - name: limit- in: query- schema:- type: integer- description: Maximum number of results (default is unlimited/None)- - name: offset- in: query- schema:- type: integer- default: 0- description: Pagination offset- responses:- "200":- description: Jobs list- content:- application/json:- schema:- type: object- properties:- jobs:- type: array- items:- $ref: "#/components/schemas/JobEntry"- pagination:- $ref: "#/components/schemas/PaginationInfo"-- '401':- description: Unauthorized - Authentication required- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/jobs/{job_id}:- get:- operationId: getJobDetail- tags: [queue]- summary: Get a single job by ID- description: Returns the full record for a single completed prompt execution, including its outputs, status, and metadata.- parameters:- - name: job_id- in: path- description: The job (prompt) ID to fetch.- required: true- schema:- type: string- format: uuid- responses:- "200":- description: Job detail- content:- application/json:- schema:- $ref: "#/components/schemas/JobDetailResponse"- "404":- description: Job not found-- '401':- description: Unauthorized - Authentication required- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '403':- description: Forbidden - Job does not belong to user- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # History- # ---------------------------------------------------------------------------- /api/history:- get:- operationId: getPromptHistory- tags: [history]- summary: Get execution history- deprecated: true- description: |- **Deprecated.** Superseded by `GET /api/jobs`, which returns the same- execution records in a paginated, filterable format. Planned for removal- no earlier than a future major release; sunset timeline TBD.-- Returns a dictionary keyed by prompt_id. Each value is a HistoryEntry- containing prompt metadata, outputs, status, and node meta.- parameters:- - $ref: "#/components/parameters/ComfyUserHeader"- - name: max_items- in: query- schema:- type: integer- description: Maximum number of history entries to return- - name: offset- in: query- schema:- type: integer- description: Pagination offset (number of entries to skip)- responses:- "200":- description: History dictionary keyed by prompt_id- content:- application/json:- schema:- type: object- additionalProperties:- $ref: "#/components/schemas/HistoryEntry"- '404':- description: "Not Found \u2014 use /api/history_v2 instead"- post:- operationId: manageHistory- tags: [history]- summary: Clear or delete history entries- deprecated: true- description: |- **Deprecated.** Superseded by the forthcoming job-management endpoints- under `/api/jobs`. Planned for removal no earlier than a future major- release; sunset timeline TBD.- parameters:- - $ref: "#/components/parameters/ComfyUserHeader"- requestBody:- required: true- content:- application/json:- schema:- $ref: "#/components/schemas/HistoryManageRequest"- responses:- "200":- description: History updated-- '400':- description: Invalid request parameters- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized - Authentication required- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/history/{prompt_id}:- get:- operationId: getHistoryByPromptId- tags: [history]- summary: Get history for a specific prompt- deprecated: true- description: |- **Deprecated.** Superseded by `GET /api/jobs/{job_id}`, which returns- the same execution record. Planned for removal no earlier than a future- major release; sunset timeline TBD.- parameters:- - $ref: "#/components/parameters/ComfyUserHeader"- - name: prompt_id- in: path- description: The prompt ID to fetch history for.- required: true- schema:- type: string- format: uuid- responses:- "200":- description: Single-entry history dictionary. Returns an empty object `{}` if the prompt_id is not found.- content:- application/json:- schema:- type: object- additionalProperties:- $ref: "#/components/schemas/HistoryEntry"-- '404':- description: "Not Found \u2014 use /api/jobs/{prompt_id} instead"- # ---------------------------------------------------------------------------- # Upload- # ---------------------------------------------------------------------------- /api/upload/image:- post:- operationId: uploadImage- tags: [upload]- summary: Upload an image file- description: Uploads an image file into one of the input/output/temp directories so it can be referenced by workflow nodes.- requestBody:- required: true- content:- multipart/form-data:- schema:- type: object- required:- - image- properties:- image:- type: string- format: binary- description: Image file to upload- type:- type: string- enum: [input, temp, output]- default: input- description: Target directory type- overwrite:- type: string- description: 'Set to "true" to overwrite existing files'- subfolder:- type: string- description: Subfolder within the target directory- responses:- "200":- description: Upload result- content:- application/json:- schema:- $ref: "#/components/schemas/UploadResult"- "400":- description: No file provided or invalid request-- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/upload/mask:- post:- operationId: uploadMask- tags: [upload]- deprecated: true- summary: Upload a mask image (deprecated)- description: |- Deprecated. Clients should composite the mask onto the source image- client-side and upload the resulting image via POST /api/upload/image- instead. This endpoint will continue to function for older clients,- but will not receive new features.-- Uploads a mask image associated with a previously-uploaded reference image.- requestBody:- required: true- content:- multipart/form-data:- schema:- type: object- required:- - image- - original_ref- properties:- image:- type: string- format: binary- description: Mask image (alpha channel is used)- original_ref:- type: object- description: Reference to the original image file- required:- - filename- properties:- filename:- type: string- description: Filename of the original image- additionalProperties: true- type:- type: string- enum: [input, temp, output]- default: input- description: Target directory type- overwrite:- type: string- description: 'Set to "true" to overwrite existing files'- subfolder:- type: string- description: Subfolder within the target directory- responses:- "200":- description: Upload result- content:- application/json:- schema:- $ref: "#/components/schemas/UploadResult"- "400":- description: No file provided or invalid request-- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # View- # ---------------------------------------------------------------------------- /api/view:- get:- operationId: viewFile- tags: [view]- summary: View or download a file- description: Serves a file (image, audio, or video) from the input/output/temp directory identified by the query parameters.- parameters:- - name: filename- in: query- required: true- schema:- type: string- description: Name of the file to view- - name: type- in: query- schema:- type: string- enum: [input, output, temp]- default: output- description: Directory type- - name: subfolder- in: query- schema:- type: string- description: Subfolder within the directory- - name: preview- in: query- schema:- type: string- description: Preview format hint (e.g. "webp;90")- - name: channel- in: query- schema:- type: string- enum: [rgba, rgb, a]- description: Channel extraction mode- responses:- "200":- description: File content- content:- image/*:- schema:- type: string- format: binary- video/*:- schema:- type: string- format: binary- audio/*:- schema:- type: string- format: binary- application/octet-stream:- schema:- type: string- format: binary- "404":- description: File not found-- '302':- description: Redirect to GCS signed URL- headers:- Location:- description: Signed URL to access the file in GCS- schema:- type: string- Cache-Control:- description: Cache directive for the redirect response- schema:- type: string- Vary:- description: Headers that affect response caching- schema:- type: string- '400':- description: Invalid request parameters- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/view_metadata/{folder_name}:- get:- operationId: viewMetadata- tags: [view]- summary: Get metadata for a file (e.g. safetensors header)- description: Returns embedded metadata parsed from a file in the given folder — for example, the header of a safetensors model.- parameters:- - name: folder_name- in: path- required: true- schema:- type: string- description: Folder type (output, input, temp, etc.)- - name: filename- in: query- required: true- schema:- type: string- description: Filename to read metadata from- responses:- "200":- description: File metadata- content:- application/json:- schema:- type: object- additionalProperties: true- "404":- description: File or metadata not found-- # ---------------------------------------------------------------------------- # System- # ---------------------------------------------------------------------------- /api/system_stats:- get:- operationId: getSystemStats- tags: [system]- summary: Get system statistics- description: Returns hardware, Python, VRAM, and runtime statistics for the running ComfyUI process.- responses:- "200":- description: System stats- content:- application/json:- schema:- $ref: "#/components/schemas/SystemStatsResponse"-- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/features:- get:- operationId: getFeatures- tags: [system]- summary: Get enabled feature flags- description: Returns a dictionary of feature flag names to their enabled state. Cloud deployments may include additional typed fields alongside the boolean flags.- responses:- "200":- description: Feature flags- content:- application/json:- schema:- type: object- additionalProperties:- type: boolean- properties:- max_upload_size:- type: integer- format: int64- minimum: 0- description: "Maximum file upload size in bytes."- free_tier_credits:- type: integer- format: int32- minimum: 0- nullable: true- x-runtime: [cloud]- description: "[cloud-only] Credits available to free-tier users. Local ComfyUI returns null."- posthog_api_host:+components:+ schemas:+ Asset:+ description: Represents a user-owned asset (image, video, or other generated output).+ properties:+ asset_hash:+ deprecated: true+ description: 'Deprecated: use hash instead. Blake3 hash of the asset content.'+ pattern: ^blake3:[a-f0-9]{64}$type: string- format: uri- nullable: true- x-runtime: [cloud]- description: "[cloud-only] PostHog analytics proxy URL for frontend telemetry. Local ComfyUI returns null."- max_concurrent_jobs:- type: integer- format: int32- minimum: 0- nullable: true- x-runtime: [cloud]- description: "[cloud-only] Maximum concurrent jobs the authenticated user can run. Local ComfyUI returns null."- workflow_templates_version:+ created_at:+ description: Timestamp when the asset was created+ format: date-timetype: string+ display_name:+ description: Display name of the asset. Mirrors name for backwards compatibility.nullable: true- x-runtime: [cloud]- description: "[cloud-only] Version identifier for the workflow templates bundle. Local ComfyUI returns null."- workflow_templates_source:type: string- nullable: true- enum: [dynamic_config_override, workflow_templates_version_json]- x-runtime: [cloud]- description: "[cloud-only] How the templates version was resolved. Local ComfyUI returns null."-- # ---------------------------------------------------------------------------- # Node / Object Info- # ---------------------------------------------------------------------------- /api/object_info:- get:- operationId: getNodeInfo- tags: [node]- summary: Get all node definitions- description: |- Returns a dictionary of every registered node class, keyed by class name.- Each value is a NodeInfo object describing inputs, outputs, category, etc.- responses:- "200":- description: All node definitions- content:- application/json:- schema:- type: object- additionalProperties:- $ref: "#/components/schemas/NodeInfo"-- /api/object_info/{node_class}:- get:- operationId: getObjectInfoByClass- tags: [node]- summary: Get a single node definition- description: Returns the `NodeInfo` definition for a single registered node class.- parameters:- - name: node_class- in: path- required: true- schema:- type: string- description: Node class name (e.g. "KSampler")- responses:- "200":- description: Single node definition- content:- application/json:- schema:- type: object- additionalProperties:- $ref: "#/components/schemas/NodeInfo"- "404":- description: Node class not found-- /api/embeddings:- get:- operationId: getEmbeddings- tags: [node]- summary: List available embedding names- description: Returns the list of text-encoder embeddings available on disk.- responses:- "200":- description: Embedding names- content:- application/json:- schema:- type: array- items:- type: string-- # ---------------------------------------------------------------------------- # Models- # ---------------------------------------------------------------------------- /api/models:- get:- operationId: getModelTypes- tags: [model]- summary: List model folder type names- description: Returns an array of model type names (e.g. checkpoints, loras, vae).- responses:- "200":- description: Model type names- content:- application/json:- schema:- type: array- items:- type: string-- '404':- description: "Not Found \u2014 use /api/experiment/models instead"- /api/models/{folder}:- get:- operationId: getModelsByFolder- tags: [model]- summary: List model filenames in a folder- description: Returns the names of model files in the given folder. This endpoint predates `/api/experiment/models/{folder}` and returns names only — prefer the experiment endpoint for new integrations.- parameters:- - name: folder- in: path- required: true- schema:- type: string- description: Model folder type name- responses:- "200":- description: Model filenames- content:- application/json:- schema:- type: array- items:- type: string- "404":- description: Unknown folder type-- /api/experiment/models:- get:- operationId: getModelFolders- 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"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/experiment/models/{folder}:- get:- operationId: getModelsInFolder- tags: [model]- summary: List model files with metadata- description: Returns the model files in the given folder with richer metadata (path index, mtime, size) than the legacy `/api/models/{folder}` endpoint.- parameters:- - name: folder- in: path- required: true- schema:- type: string- description: Model folder type name- responses:- "200":- description: Model files with metadata- content:- application/json:- schema:- type: array- items:- $ref: "#/components/schemas/ModelFile"- "404":- description: Unknown folder type-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/experiment/models/preview/{folder}/{path_index}/{filename}:- get:- operationId: getModelPreview- tags: [model]- summary: Get model preview image- description: Returns the preview image associated with a model file, if one exists alongside the model on disk.- parameters:- - name: folder- in: path- required: true- schema:- type: string- description: Model folder type name- - name: path_index- in: path- required: true- schema:- type: integer- description: Path index within the folder- - name: filename- in: path- required: true- schema:- type: string- description: Model filename- responses:- "200":- description: Preview image (WebP)- content:- image/webp:- schema:- type: string- format: binary- "404":- description: Preview not found-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # Users- # ---------------------------------------------------------------------------- /api/users:- get:- operationId: getUsersInfo- 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:+ hash:+ description: Blake3 hash of the asset content. Preferred over asset_hash.+ pattern: ^blake3:[a-f0-9]{64}$+ type: string+ id:+ description: Unique identifier for the asset+ format: uuid+ type: string+ is_immutable:+ description: Whether this asset is immutable (cannot be modified or deleted)type: boolean- 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)- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: createUser- tags: [user]- summary: Create a new user (multi-user mode)- description: Creates a new user entry. Only meaningful when ComfyUI is running in multi-user mode.- parameters:- - $ref: "#/components/parameters/ComfyUserHeader"- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - username- properties:- username:- type: string- description: Username for the new user- responses:- "200":- description: Created user ID- content:- application/json:- schema:- type: string- description: The generated user_id- "400":- description: Username already exists or invalid-- # ---------------------------------------------------------------------------- # Userdata- # ---------------------------------------------------------------------------- /api/userdata:- get:- operationId: getUserdata- tags: [userdata]- summary: List files in a userdata directory- description: Lists files in the authenticated user's data directory. Returns either filename strings or full objects depending on the `full_info` query parameter.- parameters:- - $ref: "#/components/parameters/ComfyUserHeader"- - name: dir- in: query- required: true- schema:- type: string- description: Directory path relative to the user's data folder- - name: recurse- in: query- schema:- type: boolean- description: Recurse into subdirectories- - name: full_info- in: query- schema:- type: boolean- description: Return full file info objects instead of just names- - name: split- in: query- schema:- type: boolean- description: Split paths into directory components- responses:- "200":- description: File listing- content:- application/json:- schema:- $ref: "#/components/schemas/GetUserDataResponseFull"- "404":- description: Directory not found-- '400':- description: Bad request (e.g., invalid filename).- content:- text/plain:- schema:- type: string- '401':- description: Unauthorized.- content:- text/plain:- schema:- type: string- '500':- description: General error- content:- text/plain:- schema:- type: string- /api/v2/userdata:- get:- operationId: listUserdataV2- tags: [userdata]- summary: List files in userdata (v2 format)- description: Lists files in the authenticated user's data directory using the v2 response shape, which always returns full objects.- parameters:- - $ref: "#/components/parameters/ComfyUserHeader"- - name: path- in: query- schema:- type: string- description: Directory path relative to user data root- responses:- "200":- description: File listing with metadata- 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-- '404':- description: "Not Found \u2014 use /api/userdata instead"- /api/userdata/{file}:- get:- operationId: getUserdataFile- tags: [userdata]- summary: Read a userdata file- description: Reads the contents of a file from the authenticated user's data directory.- 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- '400':- description: Bad request (e.g., invalid filename).- content:- text/plain:- schema:- type: string- '401':- description: Unauthorized.- content:- text/plain:- schema:- type: string- '500':- description: General error- content:- text/plain:- schema:- type: string- post:- operationId: postUserdataFile- tags: [userdata]- summary: Write or create a userdata file- description: Writes (creates or replaces) a file in the authenticated user's data directory.- 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/UserDataResponseFull"- "409":- description: File exists and overwrite not set- '400':- description: Missing or invalid 'file' parameter.- content:- text/plain:- schema:- type: string- '401':- description: Unauthorized.- content:- text/plain:- schema:- type: string- '403':- description: The requested path is not allowed.- content:- text/plain:- schema:- type: string- '500':- description: General error- content:- text/plain:- schema:- type: string- delete:- operationId: deleteUserdataFile- tags: [userdata]- summary: Delete a userdata file- description: Deletes a file from the authenticated user's data directory.- 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-- '401':- description: Unauthorized.- content:- text/plain:- schema:- type: string- '500':- description: Internal server error.- content:- text/plain:- schema:- type: string- /api/userdata/{file}/move/{dest}:- post:- operationId: moveUserdataFile- tags: [userdata]- summary: Move or rename a userdata file- description: Renames or moves a file within the authenticated user's data directory.- 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/UserDataResponseFull"- "404":- description: Source file not found- "409":- description: Destination exists and overwrite not set-- '400':- description: Missing or invalid parameters.- content:- text/plain:- schema:- type: string- '401':- description: Unauthorized.- content:- text/plain:- schema:- type: string- '500':- description: General error- content:- text/plain:- schema:- type: string- # ---------------------------------------------------------------------------- # Settings- # ---------------------------------------------------------------------------- /api/settings:- get:- operationId: getAllSettings- tags: [settings]- summary: Get all user settings- description: Returns all settings for the authenticated user.- parameters:- - $ref: "#/components/parameters/ComfyUserHeader"- responses:- "200":- description: Settings object- content:- application/json:- schema:- type: object- additionalProperties: true- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: updateMultipleSettings- tags: [settings]- summary: Update user settings (partial merge)- description: Replaces the authenticated user's settings with the provided object.- 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-- '400':- description: Invalid request- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/settings/{id}:- get:- operationId: getSettingById- tags: [settings]- summary: Get a single setting by key- description: Returns the value of a single setting, identified 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- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '404':- description: Setting not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: updateSettingById- tags: [settings]- summary: Set a single setting value- description: Sets the value of a single setting, identified by key.- 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-- '400':- description: Invalid request- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # Extensions / Templates / i18n- # ---------------------------------------------------------------------------- /api/extensions:- get:- operationId: getExtensions- tags: [extensions]- summary: List frontend extension JS file paths- description: Returns the list of frontend extension JS URLs registered by custom nodes, to be loaded by the frontend on startup.- 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- description: Returns the URLs of translation files contributed by custom nodes, keyed by locale.- 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"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/global_subgraphs/{id}:- get:- operationId: getGlobalSubgraph- tags: [subgraph]- summary: Get a global subgraph with full data- description: Returns the blueprint for a globally-registered subgraph, used by the frontend to materialize the subgraph node.- 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-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # 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-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # Internal (x-internal: true)- # ---------------------------------------------------------------------------- /internal/logs:- get:- operationId: getInternalLogs- tags: [internal]- summary: Get server logs as text- description: Returns structured ComfyUI log entries from the in-memory log buffer.- 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- description: Returns the raw ComfyUI log buffer as text, together with metadata about the current size limit.- 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:+ 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: truetype: 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- description: Subscribes or unsubscribes the current client from live log streaming over the WebSocket.- 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- description: Returns the filesystem paths ComfyUI is configured to load models and other assets from, keyed by folder type.- 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: getFiles- tags: [internal]- summary: List files in a directory type- description: Lists the files present in one of ComfyUI's known directories (input, output, or temp).- 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-- '400':- description: Invalid directory type- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # 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- description: Returns 204 if an asset with the given content hash already exists, 404 otherwise. Used by clients to deduplicate uploads before transferring bytes.- 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-- '400':- description: Invalid hash format- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets:- get:- operationId: listAssets- tags: [assets]- summary: List assets with filtering and pagination- description: Returns a paginated list of assets, optionally filtered by tags, name, or other query parameters.- 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- - name: include_public- in: query- schema:- type: boolean- x-runtime: [cloud]- description: "[cloud-only] Include workspace-public assets in addition to the caller's own."- - name: asset_hash- in: query- schema:- type: string- x-runtime: [cloud]- description: "[cloud-only] Filter by exact content hash."- responses:- "200":- description: Asset list- content:- application/json:- schema:- $ref: "#/components/schemas/ListAssetsResponse"- '400':- description: Invalid request parameters- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: uploadAsset- tags: [assets]- summary: Upload a new asset- description: Uploads a new asset (binary content plus metadata) and registers it in the asset database.- 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- id:- type: string- format: uuid- nullable: true- x-runtime: [cloud]- description: "[cloud-only] Client-supplied asset ID for idempotent creation. If an asset with this ID already exists, the existing asset is returned."- application/json:- schema:- type: object- x-runtime: [cloud]- description: "[cloud-only] URL-based asset upload. Caller supplies a URL instead of a file body; the server fetches the content."- required:- - url- properties:- url:- type: string- format: uri- description: "[cloud-only] URL of the file to import as an asset"+ description: MIME type of the asset+ type: stringname:- 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)+ description: Name of the asset file+ type: stringpreview_id:- type: string- format: uuid- description: ID of an existing asset to use as the preview image- id:- type: string- format: uuid- nullable: true- x-runtime: [cloud]- description: "[cloud-only] Client-supplied asset ID for idempotent creation. If an asset with this ID already exists, the existing asset is returned."- responses:- "201":- description: Asset created- content:- application/json:- schema:- $ref: "#/components/schemas/AssetCreated"-- '200':- description: Asset already exists (returned existing asset)- content:- application/json:- schema:- $ref: '#/components/schemas/AssetCreated'- '400':- description: Invalid request (bad file, invalid URL, invalid content type, etc.)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '403':- description: Source URL requires authentication or access denied- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '404':- description: Source URL not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '413':- description: File too large- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '415':- description: Unsupported media type- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '422':- description: Download failed due to network error or timeout- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets/from-hash:- post:- operationId: createAssetFromHash- tags: [assets]- summary: Create an asset reference from an existing hash- description: Registers a new asset that references existing content by hash, without re-uploading the bytes.- 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+ 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+ size:+ description: Size of the asset in bytes+ format: int64+ type: integertags:- type: array- items:+ description: Tags associated with the asset+ items:+ type: string+ type: array+ updated_at:+ description: Timestamp when the asset was last updated+ format: date-timetype: stringuser_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_newtype: object- additionalProperties: true- mime_type:- type: string- nullable: true- x-runtime: [cloud]- description: "[cloud-only] MIME type of the content, so the type is preserved without re-inspecting content. Ignored by local ComfyUI."- responses:- "201":- description: Asset created from hash- content:- application/json:- schema:- $ref: "#/components/schemas/AssetCreated"-- '200':- description: Asset reference already exists (returned existing)- content:- application/json:- schema:- $ref: '#/components/schemas/AssetCreated'- '400':- description: Invalid request (bad hash format, invalid tags, etc.)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '404':- description: Source asset with given hash not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets/{id}:- get:- operationId: getAssetById- tags: [assets]- summary: Get asset metadata- description: Returns the metadata for a single asset.- x-feature-gate: enable-assets- parameters:- - name: id- in: path- description: The asset ID.- 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- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- put:- operationId: updateAsset- tags: [assets]- summary: Update asset metadata- description: Updates the mutable metadata of an asset (name, tags, etc.). Binary content is immutable.- x-feature-gate: enable-assets- parameters:- - name: id- in: path- description: The asset ID.- required: true- schema:- type: string- format: uuid- requestBody:- required: true- content:- application/json:- schema:- type: object- properties:+ 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: booleanname:- 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- mime_type:- type: string- nullable: true- x-runtime: [cloud]- description: "[cloud-only] MIME type override when auto-detection was wrong. Ignored by local ComfyUI."- responses:- "200":- description: Asset updated- content:- application/json:- schema:- $ref: "#/components/schemas/AssetUpdated"- '400':- description: Invalid request (no fields provided)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '404':- description: Asset not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- delete:- operationId: deleteAsset- tags: [assets]- summary: Delete an asset- description: Removes an asset entry. Depending on the server configuration, the underlying content may also be deleted.- x-feature-gate: enable-assets- parameters:- - name: id- in: path- description: The asset ID.- 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-- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '404':- description: Asset not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '409':- description: Asset cannot be deleted because it is referenced by another resource (e.g., workflow version)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets/{id}/content:- get:- operationId: getAssetContent- tags: [assets]- summary: Download asset file content- description: Returns the binary content of an asset. Supports range requests.- x-feature-gate: enable-assets- parameters:- - name: id- in: path- description: The asset ID.- 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- description: Adds one or more tags to an asset.- x-feature-gate: enable-assets- parameters:- - name: id- in: path- description: The asset ID.- 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"- '400':- description: Invalid request- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '404':- description: Asset not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '422':- description: Validation error (e.g., reserved tag)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- delete:- operationId: removeAssetTags- tags: [assets]- summary: Remove tags from an asset- description: Removes one or more tags from an asset.- x-feature-gate: enable-assets- parameters:- - name: id- in: path- description: The asset ID.- 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"-- '400':- description: Invalid request- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '404':- description: Asset not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '422':- description: Validation error (e.g., reserved tag)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/tags:- get:- operationId: listTags- tags: [assets]- summary: List all known tags with counts- description: Returns the list of all tags known to the asset database, 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"-- '400':- description: Invalid request parameters- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets/tags/refine:- get:- operationId: getAssetTagHistogram- tags: [assets]- summary: Get tag counts for assets matching current filters- description: Returns suggested additional tags that would refine a filtered asset query, together with the count of assets each tag would select.- 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"-- '400':- description: Invalid request parameters- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets/seed:- post:- operationId: seedAssets- tags: [assets]- summary: Trigger asset scan/seed from filesystem- description: Starts a background job that scans the configured directories and registers any assets not yet present in the asset database.- 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- description: Returns the progress and status of the most recently-started asset seed job.- 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- description: Requests cancellation of the currently-running asset seed job.- x-feature-gate: enable-assets- responses:- "200":- description: Scan cancelled- content:- application/json:- schema:- type: object- properties:- status:+ preview_url:+ description: Signed URL for previewing the asset.type: string-- /api/assets/prune:- post:- operationId: pruneAssets- tags: [assets]- summary: Mark assets whose backing files no longer exist on disk- description: Starts a background job that removes asset entries whose underlying content no longer exists 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-- # ===========================================================================- # Cloud-runtime FE-facing operations- #- # These operations are served by the cloud runtime. The local runtime returns- # 404 for all of these paths. Each operation is tagged x-runtime: [cloud].- # ===========================================================================-- # ---------------------------------------------------------------------------- # Jobs / prompts (cloud)- # ---------------------------------------------------------------------------- /api/jobs/{job_id}/cancel:- post:- operationId: cancelJob- tags: [queue]- summary: Cancel a running or pending job- description: "[cloud-only] Requests cancellation of a job. If the job is currently executing, execution is interrupted. If it is pending in the queue, it is removed."- x-runtime: [cloud]- parameters:- - name: job_id- in: path- required: true- schema:- type: string- format: uuid- description: The job ID to cancel.- responses:- "200":- description: Cancellation accepted- content:- application/json:- schema:- $ref: "#/components/schemas/JobCancelResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '400':- description: Bad Request - job_id is not a valid UUID (emitted by request validation before the handler runs)- content:- application/json:- schema:- $ref: '#/components/schemas/BindingErrorResponse'- '500':- description: Internal server error - cancellation failed- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/job/{job_id}/status:- get:- operationId: getJobStatus- tags: [queue]- summary: Get status of a cloud job- deprecated: true- description: |- **Deprecated.** This endpoint is superseded by `GET /api/jobs/{job_id}`.- Clients should migrate; the endpoint is retained for backward- compatibility but will be removed in a future release.- x-runtime: [cloud]- parameters:- - name: job_id- in: path- required: true- schema:- type: string- format: uuid- description: The job ID to check status for.- responses:- "200":- description: Job status- content:- application/json:- schema:- $ref: "#/components/schemas/JobStatusResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '403':- description: Forbidden - job belongs to another user- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/prompt/{prompt_id}:- get:- operationId: getCloudPrompt- tags: [prompt]- summary: Get a cloud prompt by ID- description: "[cloud-only] Returns the full prompt record for a cloud-executed prompt, including the submitted workflow graph and execution metadata."- x-runtime: [cloud]- parameters:- - name: prompt_id- in: path- required: true- schema:- type: string- format: uuid- description: The prompt ID to fetch.- responses:- "200":- description: Cloud prompt detail- content:- application/json:- schema:- $ref: "#/components/schemas/CloudPrompt"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /api/history_v2:- get:- operationId: getHistory- tags: [history]- summary: Get paginated execution history (v2)- deprecated: true- description: |- **Deprecated.** This endpoint is superseded by `GET /api/jobs`.- Clients should migrate; the endpoint is retained for backward- compatibility but will be removed in a future release.- x-runtime: [cloud]- parameters:- - name: limit- in: query- schema:- type: integer- default: 20- description: Maximum number of results- - name: offset- in: query- schema:- type: integer- default: 0- description: Pagination offset- - name: status- in: query- schema:- type: string- description: Filter by execution status- responses:- "200":- description: History list- content:- application/json:- schema:- $ref: "#/components/schemas/HistoryResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/history_v2/{prompt_id}:- get:- operationId: getHistoryForPrompt- tags: [history]- summary: Get v2 history for a specific prompt- deprecated: true- description: |- **Deprecated.** This endpoint is superseded by `GET /api/jobs/{prompt_id}`.- Clients should migrate; the endpoint is retained for backward- compatibility but will be removed in a future release.- x-runtime: [cloud]- parameters:- - name: prompt_id- in: path- required: true- schema:- type: string- format: uuid- description: The prompt ID to fetch history for.- responses:- "200":- description: History entry- content:- application/json:- schema:- $ref: "#/components/schemas/HistoryDetailResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/logs:- get:- operationId: getLogs- tags: [system]- summary: Get cloud execution logs- deprecated: true- description: |- **Deprecated.** This endpoint returns a static placeholder response and- provides no real log data. It is retained only to avoid breaking clients- that still call it. Clients should remove their dependency; the endpoint- will be removed in a future release.- x-runtime: [cloud]- parameters:- - name: job_id- in: query- schema:- type: string- description: Filter logs by job ID- - name: limit- in: query- schema:- type: integer- default: 100- description: Maximum number of log entries- - name: offset- in: query- schema:- type: integer- default: 0- description: Pagination offset- responses:- "200":- description: Log entries- content:- application/json:- schema:- $ref: "#/components/schemas/LogsResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- # ---------------------------------------------------------------------------- # Assets extensions (cloud)- # ---------------------------------------------------------------------------- /api/assets/download:- post:- operationId: createAssetDownload- tags: [assets]- summary: Download assets to cloud runtime- description: "[cloud-only] Initiates a download of one or more assets to the cloud runtime environment. Returns a task ID for tracking download progress via WebSocket."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - assets- properties:- assets:- type: array- items:- $ref: "#/components/schemas/AssetDownloadRequest"- description: Assets to download- responses:- "202":- description: Download task accepted- content:- application/json:- schema:- type: object- required:- - task_id- - status- properties:- task_id:+ public:+ description: Whether this is a public (platform-provided) asset.+ type: boolean+ storage_url:type: string- format: uuid- description: ID of the download task; use to poll status.- status:- type: string- enum: [created, running, completed, failed]- description: Current task status (typically `created` on initial creation).- message:- type: string- description: Human-readable task message.- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '200':- description: File already exists in storage - asset created/returned immediately- content:- application/json:- schema:- $ref: '#/components/schemas/AssetCreated'- '422':- description: Validation errors- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets/export:- post:- operationId: createAssetExport- tags: [assets]- summary: Export assets as a downloadable archive- description: "[cloud-only] Initiates a bulk export of assets. Returns a task ID for tracking progress via WebSocket. When complete, the export can be downloaded via the exports endpoint."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- properties:- job_ids:- type: array- items:- type: string- description: Job IDs whose associated assets should all be included in the ZIP bundle.- asset_ids:- type: array- items:+ required:+ - id+ - name+ - preview_url+ - storage_url+ - model+ - public+ - in_library+ type: object+ AssetTagHistogramResponse:+ description: Histogram of tag counts used for refining asset search results.+ properties:+ tag_counts:+ additionalProperties:+ type: integer+ description: Map of tag names to their occurrence counts on matching assets+ example:+ checkpoint: 32+ lora: 193+ vae: 6+ type: object+ required:+ - tag_counts+ type: object+ AssetUpdated:+ description: Response returned when an existing asset is successfully updated.+ properties:+ asset_hash:+ deprecated: true+ description: 'Deprecated: use hash instead. Blake3 hash of the asset content.'+ pattern: ^blake3:[a-f0-9]{64}$+ type: string+ display_name:+ description: Display name of the asset. Mirrors name for backwards compatibility.+ nullable: true+ type: string+ hash:+ description: Blake3 hash of the asset content. Preferred over asset_hash.+ pattern: ^blake3:[a-f0-9]{64}$type: string+ id:+ description: Asset IDformat: uuid- description: Asset IDs to include in the ZIP bundle. Additive to assets associated with provided job IDs.- export_name:- type: string- description: Name for the export archive- naming_strategy:- type: string- enum: [group_by_job_id, preserve, asset_id, group_by_job_time]- default: group_by_job_time- description: "Strategy for naming files in the ZIP: group by job ID, preserve original names, use the asset ID, or group by job creation time."- job_asset_name_filters:- type: object- additionalProperties:- type: array- minItems: 1- items:- type: string- description: Optional per-job asset name filters. When provided for a job ID, only assets whose name matches one of the listed names are included.- responses:- "202":- description: Export task accepted- content:- application/json:- schema:- type: object- required:- - task_id- - status- properties:- task_id:type: string+ job_id:+ description: ID of the job that created this asset, if availableformat: uuid- description: ID of the export task; use to poll status.- status:- type: string- enum: [created, running, completed, failed]- description: Current task status (typically `created` on initial creation).- message:- type: string- description: Human-readable task message.- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets/exports/{exportName}:- get:- operationId: getAssetExport- tags: [assets]- summary: Download a completed asset export- description: "[cloud-only] Returns the archive file for a completed asset export."- x-runtime: [cloud]- parameters:- - name: exportName- in: path- required: true- schema:- type: string- description: Name of the export to download- responses:- "200":- description: Export archive file- content:- application/zip:- schema:- type: string- format: binary- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '400':- description: Invalid export name- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets/from-workflow:- post:- operationId: postAssetsFromWorkflow- tags: [assets]- summary: Create asset records from a workflow execution- description: "[cloud-only] Registers output files from a workflow execution as assets in the asset database."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - prompt_id- properties:- prompt_id:- type: string- format: uuid- description: Prompt ID whose outputs should be registered as assets+ nullable: true+ type: string+ mime_type:+ description: Updated MIME type of the asset+ type: string+ name:+ description: Updated name of the asset+ type: stringtags:- type: array- items:- type: string- description: Tags to apply to the created assets- responses:- "200":- description: Assets created or referenced- content:- application/json:- schema:- type: object- properties:- assets:- type: array+ description: Tags associated with the assetitems:- $ref: "#/components/schemas/Asset"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets/import:- post:- operationId: importPublishedAssets- tags: [assets]- summary: "[cloud-only] Import published assets into the caller's library"- description: |- [cloud-only] Imports the specified published assets into the caller's asset library. New DB records reference the same storage objects; no file copying occurs. Assets the caller already owns (by hash) are deduplicated. The `id` field on each returned `AssetInfo` is the caller's newly-created private asset ID, not the published asset ID supplied in the request.- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- $ref: "#/components/schemas/ImportPublishedAssetsRequest"- responses:- "200":- description: Successfully imported assets- content:- application/json:- schema:- $ref: "#/components/schemas/ImportPublishedAssetsResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/assets/remote-metadata:- get:- operationId: getRemoteAssetMetadata- tags: [assets]- summary: Fetch metadata for a remote asset URL- description: "[cloud-only] Fetches and returns metadata (content type, size, filename) for a remote URL without downloading the full content."- x-runtime: [cloud]- parameters:- - name: url- in: query- required: true- schema:- type: string- format: uri- description: URL to inspect- responses:- "200":- description: Remote metadata- content:- application/json:- schema:- $ref: "#/components/schemas/AssetMetadataResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '422':- description: Failed to retrieve metadata from source- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # Custom nodes / hub (cloud)- # ---------------------------------------------------------------------------- /api/experiment/nodes:- get:- operationId: getNodeInfoSchema- tags: [runtime-only]- summary: Get pre-rendered node info schema- description: "[cloud-only] Returns the static ComfyUI object_info schema, identical for every caller, rendered once at startup with empty model/user-file context. Served by a raw HTTP handler that writes pre-rendered bytes with ETag + Cache-Control validators for RFC 7232 conditional GETs."- x-runtime: [cloud]- parameters:- - name: If-None-Match- in: header- required: false- schema:- type: string- description: Entity tag previously returned by this endpoint. When present and matching, the server returns 304 Not Modified.- responses:- "200":- description: Node info schema- headers:- ETag:- schema:- type: string- description: Entity tag for conditional request validation- Cache-Control:- schema:- type: string- description: Cache directives for the response- content:- application/json:- schema:- type: object- additionalProperties:- $ref: "#/components/schemas/NodeInfo"- "304":- description: Not Modified — returned when the client sends a matching If-None-Match header- post:- operationId: installCloudNode- tags: [node]- summary: Install a custom node package- description: "[cloud-only] Installs a custom node package in the cloud runtime by ID or repository URL."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:+ 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- properties:- id:- type: string- description: Node package ID or repository URL- version:- type: string- description: Specific version to install- responses:- "200":- description: Node installed- content:- application/json:- schema:- $ref: "#/components/schemas/CloudNode"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /api/experiment/nodes/{id}:- get:- operationId: getNodeByID- tags: [runtime-only]- summary: Get a single node definition by ID- description: "[cloud-only] Returns one node's definition from the pre-indexed object_info schema. Served by a raw HTTP handler that writes pre-rendered bytes with ETag + Cache-Control validators for RFC 7232 conditional GETs."- x-runtime: [cloud]- parameters:- - name: id- in: path- required: true- schema:- type: string- description: Node class identifier- - name: If-None-Match- in: header- required: false- schema:- type: string- description: Entity tag previously returned by this endpoint. When present and matching, the server returns 304 Not Modified.- responses:- "200":- description: Single node definition- headers:- ETag:- schema:- type: string- description: Entity tag for conditional request validation- Cache-Control:- schema:- type: string- description: Cache directives for the response- content:- application/json:- schema:- $ref: "#/components/schemas/NodeInfo"- "304":- description: Not Modified — returned when the client sends a matching If-None-Match header- "404":- description: Node not found- delete:- operationId: uninstallCloudNode- tags: [node]- summary: Uninstall a custom node package- description: "[cloud-only] Removes a custom node package from the cloud runtime."- x-runtime: [cloud]- parameters:- - name: id- in: path- required: true- schema:- type: string- description: Custom node package ID- responses:- "204":- description: Node uninstalled- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /api/hub/assets/upload-url:- post:- operationId: createHubAssetUploadUrl- tags: [hub]- summary: Get a pre-signed upload URL for a hub asset- description: "[cloud-only] Returns a pre-signed URL that can be used to upload an asset file directly to storage."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - filename- - content_type- properties:- filename:- type: string- description: Name of the file to upload- content_type:- type: string- description: MIME type of the file- size:- type: integer- format: int64- description: File size in bytes- responses:- "200":- description: Upload URL- content:- application/json:- schema:- type: object- properties:- upload_url:+ - updated_at+ type: object+ CreateWorkflowRequest:+ description: Request body for creating a new saved workflow.+ properties:+ default_view:+ description: Default view mode+ enum:+ - workflow+ - apptype: string- format: uri- description: Pre-signed upload URL- asset_url:+ description:+ description: Description of the workflowtype: string- format: uri- description: Public URL after upload completes- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '404':- description: Not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/hub/labels:- get:- operationId: listHubLabels- tags: [hub]- summary: List available hub labels- description: "[cloud-only] Returns the list of labels/categories available for tagging hub content."- x-runtime: [cloud]- responses:- "200":- description: Label list- content:- application/json:- schema:- $ref: "#/components/schemas/HubLabelListResponse"- '400':- description: Bad request (e.g. invalid type parameter)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/hub/profiles:- get:- operationId: listHubProfiles- tags: [hub]- summary: List hub user profiles- description: "[cloud-only] Returns a paginated list of public hub user profiles."- x-runtime: [cloud]- parameters:- - name: limit- in: query- schema:- type: integer- description: Maximum number of results- - name: offset- in: query- schema:- type: integer- description: Pagination offset- - name: search- in: query- schema:- type: string- description: Search by username or display name- responses:- "200":- description: Profile list- content:- application/json:- schema:- type: object- properties:- profiles:- type: array- items:- $ref: "#/components/schemas/HubProfile"- total:- type: integer- has_more:- type: boolean- post:- operationId: createHubProfile- tags: [hub]- summary: Create a Hub profile- description: "[cloud-only] Creates a hub profile for the specified workspace. Username is immutable after creation."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- $ref: "#/components/schemas/CreateHubProfileRequest"- responses:- "201":- description: Hub profile created- content:- application/json:- schema:- $ref: "#/components/schemas/HubProfile"- "400":- description: Bad request (e.g. invalid username)- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "409":- description: Username already taken or profile already exists- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/hub/profiles/{username}:- get:- operationId: getHubProfile- tags: [hub]- summary: Get a hub profile by username- description: "[cloud-only] Returns the public hub profile for the given username."- x-runtime: [cloud]- parameters:- - name: username- in: path- required: true- schema:- type: string- description: Hub username- responses:- "200":- description: Profile- content:- application/json:- schema:- $ref: "#/components/schemas/HubProfile"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/hub/profiles/check:- get:- operationId: checkHubUsername- tags: [hub]- summary: Check if a hub username is available- description: "[cloud-only] Returns whether the given username is available for registration."- x-runtime: [cloud]- parameters:- - name: username- in: query- required: true- schema:- type: string- description: Username to check- responses:- "200":- description: Availability result- content:- application/json:- schema:- type: object- properties:- available:- type: boolean- username:+ forked_from_workflow_id:+ description: ID of the source workflow if forkedtype: string-- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '404':- description: Not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/hub/profiles/me:- get:- operationId: getMyHubProfile- tags: [hub]- summary: Get the authenticated user's hub profile- description: "[cloud-only] Returns the hub profile of the currently authenticated user."- x-runtime: [cloud]- responses:- "200":- description: Profile- content:- application/json:- schema:- $ref: "#/components/schemas/HubProfile"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '404':- description: No hub profile exists- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- put:- operationId: updateMyHubProfile- tags: [hub]- summary: Update the authenticated user's hub profile- description: "[cloud-only] Updates the hub profile of the currently authenticated user."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- properties:- username:- type: string- display_name:- type: string- bio:- type: string- avatar_url:- type: string- format: uri- links:- type: array- items:+ forked_from_workflow_version_id:+ description: ID of the source workflow version if forkedtype: string- format: uri- responses:- "200":- description: Updated profile- content:- application/json:- schema:- $ref: "#/components/schemas/HubProfile"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "409":- description: Conflict- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /api/hub/workflows:- get:- operationId: listHubWorkflows- tags: [hub]- summary: List published hub workflows- description: "[cloud-only] Returns a paginated list of publicly shared workflows on the hub."- x-runtime: [cloud]- parameters:- - name: limit- in: query- schema:- type: integer- description: Maximum number of results- - name: offset- in: query- schema:- type: integer- description: Pagination offset- - name: sort- in: query- schema:- type: string- description: Sort field (e.g. created_at, likes)- - name: order- in: query- schema:- type: string- enum: [asc, desc]- description: Sort direction- - name: search- in: query- schema:- type: string- description: Search by title or description- - name: labels- in: query- schema:- type: string- description: Filter by label IDs (comma-separated)- responses:- "200":- description: Hub workflow list- content:- application/json:- schema:- $ref: "#/components/schemas/HubWorkflowListResponse"- '400':- description: Bad request (e.g. malformed pagination cursor)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '404':- description: Profile not found (when filtering by username)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: publishHubWorkflow- tags: [hub]- summary: Publish a workflow to the hub- description: "[cloud-only] Publishes a workflow to the hub with metadata, thumbnail, and sample images."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- $ref: "#/components/schemas/PublishHubWorkflowRequest"- responses:- "200":- description: Workflow published to hub- content:- application/json:- schema:- $ref: "#/components/schemas/HubWorkflowDetail"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Workflow or profile not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/hub/workflows/{share_id}:- get:- operationId: getHubWorkflow- tags: [hub]- summary: Get a published hub workflow by share ID- description: "[cloud-only] Returns the full details of a published workflow on the hub."- x-runtime: [cloud]- parameters:- - name: share_id- in: path- required: true- schema:- type: string- description: Workflow share ID- responses:- "200":- description: Hub workflow- content:- application/json:- schema:- $ref: "#/components/schemas/HubWorkflowDetail"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '413':- description: Workflow JSON too large- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- delete:- operationId: deleteHubWorkflow- tags: [hub]- summary: Unpublish a workflow from the hub- description: "[cloud-only] Removes a workflow from the hub listing."- x-runtime: [cloud]- parameters:- - name: share_id- in: path- required: true- schema:- type: string- description: Workflow share ID- responses:- "204":- description: Successfully unpublished- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Workflow not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/hub/workflows/index:- get:- operationId: listHubWorkflowIndex- tags: [hub]- summary: Get the hub workflow index- description: "[cloud-only] Returns the lightweight index of all hub workflows for client-side search and navigation."- x-runtime: [cloud]- responses:- "200":- description: Workflow index- content:- application/json:- schema:- type: array- items:- $ref: "#/components/schemas/HubWorkflowIndexEntry"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # Workflows (cloud)- # ---------------------------------------------------------------------------- /api/workflows:- get:- operationId: listWorkflows- tags: [workflows]- summary: List cloud workflows- description: "[cloud-only] Returns a paginated list of the authenticated user's cloud workflows."- x-runtime: [cloud]- parameters:- - name: limit- in: query- schema:- type: integer- description: Maximum number of results- - name: offset- in: query- schema:- type: integer- description: Pagination offset- - name: sort- in: query- schema:- type: string- description: Sort field- - name: order- in: query- schema:- type: string- enum: [asc, desc]- description: Sort direction- - name: search- in: query- schema:- type: string- description: Search by workflow name- responses:- "200":- description: Workflow list- content:- application/json:- schema:- $ref: "#/components/schemas/WorkflowListResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: createWorkflow- tags: [workflows]- summary: Create a new cloud workflow- description: "[cloud-only] Creates a new cloud workflow with the provided name and optional initial content."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - name- properties:- name:- type: string- description: Workflow name- description:- type: string- description: Workflow description- content:- type: object- additionalProperties: true- description: Initial workflow graph JSON- responses:- "201":- description: Workflow created- content:- application/json:- schema:- $ref: "#/components/schemas/WorkflowResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '422':- description: Validation error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workflows/{workflow_id}:- get:- operationId: getWorkflow- tags: [workflows]- summary: Get a cloud workflow by ID- description: "[cloud-only] Returns the metadata for a cloud workflow."- x-runtime: [cloud]- parameters:- - name: workflow_id- in: path- required: true- schema:- type: string- format: uuid- description: The workflow ID.- responses:- "200":- description: Workflow detail- content:- application/json:- schema:- $ref: "#/components/schemas/WorkflowResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '403':- description: Forbidden- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- patch:- operationId: updateWorkflow- tags: [workflows]- summary: Update a cloud workflow- description: "[cloud-only] Updates the metadata (name, description) of an existing cloud workflow."- x-runtime: [cloud]- parameters:- - name: workflow_id- in: path- required: true- schema:- type: string- format: uuid- description: The workflow ID.- requestBody:- required: true- content:- application/json:- schema:- type: object- properties:name:- type: string- description:- type: string- responses:- "200":- description: Workflow updated- content:- application/json:- schema:- $ref: "#/components/schemas/WorkflowResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '422':- description: Validation error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- delete:- operationId: deleteWorkflow- tags: [workflows]- summary: Delete a cloud workflow- description: "[cloud-only] Deletes a cloud workflow and all its versions."- x-runtime: [cloud]- parameters:- - name: workflow_id- in: path- required: true- schema:- type: string- format: uuid- description: The workflow ID.- responses:- "204":- description: Workflow deleted- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workflows/{workflow_id}/content:- get:- operationId: getWorkflowContent- tags: [workflows]- summary: Get the content of a cloud workflow- description: "[cloud-only] Returns the full workflow graph JSON for the latest version of a cloud workflow."- x-runtime: [cloud]- parameters:- - name: workflow_id- in: path- required: true- schema:- type: string- format: uuid- description: The workflow ID.- - name: version_id- in: query- schema:- type: string- description: Specific version ID to fetch- responses:- "200":- description: Workflow content- content:- application/json:- schema:- type: object- additionalProperties: true- description: The full workflow graph JSON- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '403':- description: Forbidden- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- put:- operationId: updateCloudWorkflowContent- tags: [workflows]- summary: Update the content of a cloud workflow- description: "[cloud-only] Saves new workflow graph JSON as a new version of the cloud workflow."- x-runtime: [cloud]- parameters:- - name: workflow_id- in: path- required: true- schema:- type: string- format: uuid- description: The workflow ID.- requestBody:- required: true- content:- application/json:- schema:- type: object- additionalProperties: true- description: The workflow graph JSON to save- responses:- "200":- description: Content updated- content:- application/json:- schema:- $ref: "#/components/schemas/CloudWorkflowVersion"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /api/workflows/{workflow_id}/fork:- post:- operationId: forkWorkflow- tags: [workflows]- summary: Fork a cloud workflow- description: "[cloud-only] Creates a copy of a cloud workflow under the authenticated user's account."- x-runtime: [cloud]- parameters:- - name: workflow_id- in: path- required: true- schema:- type: string- format: uuid- description: The workflow ID to fork.- requestBody:- required: false- content:- application/json:- schema:- type: object- properties:- name:- type: string- description: Name for the forked workflow (defaults to original name)- responses:- "201":- description: Forked workflow- content:- application/json:- schema:- $ref: "#/components/schemas/WorkflowResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '403':- description: Forbidden- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '422':- description: Validation error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workflows/{workflow_id}/versions:- get:- operationId: listCloudWorkflowVersions- tags: [workflows]- summary: List versions of a cloud workflow- description: "[cloud-only] Returns the version history of a cloud workflow."- x-runtime: [cloud]- parameters:- - name: workflow_id- in: path- required: true- schema:- type: string- format: uuid- description: The workflow ID.- - name: limit- in: query- schema:- type: integer- description: Maximum number of results- - name: offset- in: query- schema:- type: integer- description: Pagination offset- responses:- "200":- description: Version list- content:- application/json:- schema:- type: object- properties:- versions:- type: array- items:- $ref: "#/components/schemas/CloudWorkflowVersion"- total:- type: integer- has_more:- type: boolean- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- post:- operationId: createWorkflowVersion- tags: [workflows]- summary: Create a new cloud workflow version- description: "[cloud-only] Creates a new workflow version with updated workflow JSON. Uses optimistic concurrency via base_version."- x-runtime: [cloud]- parameters:- - name: workflow_id- in: path- required: true- schema:- type: string- format: uuid- description: The workflow ID.- requestBody:- required: true- content:- application/json:- schema:- $ref: "#/components/schemas/CreateWorkflowVersionRequest"- responses:- "201":- description: Version created- content:- application/json:- schema:- $ref: "#/components/schemas/WorkflowVersionResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden — not the workflow owner- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "409":- description: Version conflict — base_version does not match latest- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '422':- description: Validation error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workflows/published/{share_id}:- get:- operationId: getPublishedWorkflow- tags: [workflows]- summary: Get a published workflow by share ID- description: "[cloud-only] Returns a publicly published cloud workflow by its share identifier."- x-runtime: [cloud]- parameters:- - name: share_id- in: path- required: true- schema:- type: string- description: The workflow share ID.- responses:- "200":- description: Published workflow- content:- application/json:- schema:- $ref: "#/components/schemas/PublishedWorkflowDetail"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '413':- description: Workflow JSON too large- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # Auth / session (cloud)- # ---------------------------------------------------------------------------- /api/auth/session:- get:- operationId: getAuthSession- tags: [auth]- summary: Get the current authentication session- description: "[cloud-only] Returns the current session state for the authenticated user, including user identity and active workspace."- x-runtime: [cloud]- responses:- "200":- description: Session info- content:- application/json:- schema:- $ref: "#/components/schemas/AuthSession"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- post:- operationId: createSession- tags: [auth]- summary: Create a session cookie- description: "[cloud-only] Creates a session cookie from the bearer token in the Authorization header. Returns a Set-Cookie header with a secure HttpOnly session cookie. Cookie authentication is not allowed for this endpoint."- x-runtime: [cloud]- responses:- "200":- description: Session created- content:- application/json:- schema:- $ref: "#/components/schemas/CreateSessionResponse"- "400":- description: Bad request — invalid or expired ID token- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- delete:- operationId: deleteSession- tags: [auth]- summary: Delete session cookie (logout)- description: "[cloud-only] Clears the session cookie and optionally revokes the session on the server."- x-runtime: [cloud]- responses:- "200":- description: Session deleted- content:- application/json:- schema:- $ref: "#/components/schemas/DeleteSessionResponse"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/auth/token:- post:- operationId: exchangeToken- tags: [auth]- summary: Exchange credentials for an access token- description: "[cloud-only] Exchanges authentication credentials (e.g. an authorization code) for an access token."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - grant_type- properties:- grant_type:- type: string- enum: [authorization_code, refresh_token]- description: OAuth2 grant type+ 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- description: Authorization code (for authorization_code grant)- refresh_token:- type: string- description: Refresh token (for refresh_token grant)- redirect_uri:- type: string- format: uri- description: Redirect URI used in the authorization request- responses:- "200":- description: Token response- content:- application/json:- schema:- $ref: "#/components/schemas/ExchangeTokenResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '404':- description: Workspace not found or user not a member- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /.well-known/jwks.json:- get:- operationId: getJwks- tags: [auth]- summary: Get JSON Web Key Set- description: "[cloud-only] Returns the JSON Web Key Set (JWKS) used to verify JWTs issued by the cloud authentication service."- x-runtime: [cloud]- responses:- "200":- description: JWKS- content:- application/json:- schema:- $ref: "#/components/schemas/JwksResponse"-- # ---------------------------------------------------------------------------- # OAuth 2.1 / RFC 7591 Dynamic Client Registration (cloud)- # ---------------------------------------------------------------------------- /.well-known/oauth-authorization-server:- get:- operationId: getOAuthAuthorizationServer- tags: [auth]- summary: "[cloud-only] OAuth 2.1 authorization-server metadata (RFC 8414)"- description: "[cloud-only] Public metadata document for OAuth 2.1 clients. Cached 5 minutes."- x-runtime: [cloud]- security: []- responses:- "200":- description: Authorization-server metadata- content:- application/json:- schema:- $ref: "#/components/schemas/OAuthAuthorizationServerMetadata"- "404":- description: OAuth disabled- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /.well-known/oauth-protected-resource:- get:- operationId: getOAuthProtectedResource- tags: [auth]- summary: "[cloud-only] OAuth 2.1 protected-resource metadata (RFC 9728)"- description: "[cloud-only] Public metadata describing the currently advertised protected resource. Cached 5 minutes."- x-runtime: [cloud]- security: []- responses:- "200":- description: Protected-resource metadata- content:- application/json:- schema:- $ref: "#/components/schemas/OAuthProtectedResourceMetadata"- "404":- description: OAuth disabled or no active resource configured- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /oauth/authorize:- get:- operationId: getOAuthAuthorize- tags: [auth]- summary: "[cloud-only] Begin or resume an OAuth 2.1 authorization request"- description: |- [cloud-only] Two modes:- - **Initial entry** (OAuth params present): validates client/redirect/resource/scopes, persists a server-side authorization-request row, and either redirects (no session / unverified email) to the configured frontend login URL carrying only the opaque `oauth_request_id`, or returns the JSON consent challenge for the frontend to render.- - **Resume** (`oauth_request_id` present): loads the server-side row, fails closed if expired/consumed/unknown, returns the JSON consent challenge. Browser-replayed OAuth params are intentionally ignored.-- The frontend renders the consent UI from the JSON payload and POSTs the user's decision back to this endpoint.- x-runtime: [cloud]- security: []- parameters:- - { name: response_type, in: query, required: false, schema: { type: string } }- - { name: client_id, in: query, required: false, schema: { type: string } }- - { name: redirect_uri, in: query, required: false, schema: { type: string } }- - { name: scope, in: query, required: false, schema: { type: string } }- - name: state- in: query- required: false- schema: { type: string }- description: |- RFC 6749 §10.12 marks `state` as RECOMMENDED. Cloud hardening makes it REQUIRED on the initial-entry path (omitted only on the resume path where `oauth_request_id` is supplied instead). This parameter is `required: false` at the spec level only because the operation is dual-mode (initial entry vs. resume); the runtime rejects empty `state` on the initial-entry path with a stable `invalid_request` 400.- - { name: code_challenge, in: query, required: false, schema: { type: string } }- - { name: code_challenge_method, in: query, required: false, schema: { type: string } }- - { name: resource, in: query, required: false, schema: { type: string } }- - { name: oauth_request_id, in: query, required: false, schema: { type: string } }- responses:- "200":- description: Consent challenge payload (session present, email verified). Frontend renders the consent UI from this payload and POSTs back to /oauth/authorize.- content:- application/json:- schema:- $ref: "#/components/schemas/OAuthConsentChallenge"- "302":- description: Redirect to login (no session / unverified email) or to registered redirect_uri (pre-validated client error)- headers:- Location:- schema:- type: string- "400":- description: Invalid authorize request (pre-redirect failure — unknown client, redirect mismatch, malformed params)- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: OAuth disabled- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- post:- operationId: postOAuthAuthorize- tags: [auth]- summary: "[cloud-only] Submit OAuth consent decision"- description: |- [cloud-only] JSON-only consent submission. The handler verifies the per-row CSRF token, atomically marks the authorization request consumed (single-use covers both allow and deny paths), then returns the redirect URL the browser must navigate to. The URL contains either `code` + original `state` for allow, or the RFC 6749 §5.2 error and `state` for deny.-- Workspace membership is re-checked at submission time. Consent is persisted keyed by `(user_id, client_id, resource_id, workspace_id)`; broadening the previously approved scope set requires a fresh consent flow.- x-runtime: [cloud]- security: []- requestBody:- required: true- content:- application/json:- schema:- type: object- required: [oauth_request_id, csrf_token, decision, workspace_id]- properties:- oauth_request_id: { type: string, format: uuid }- csrf_token: { type: string }- decision: { type: string, enum: [allow, deny] }- workspace_id: { type: string }- responses:- "200":- description: Redirect URL for the frontend to navigate to (allow → with code+state; deny → with error+state)- content:- application/json:- schema:- $ref: "#/components/schemas/OAuthAuthorizeRedirectResponse"- "400":- description: Bad request (CSRF mismatch, expired/consumed request, inaccessible workspace)- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Scope broadening on consent re-grant — fresh consent flow required- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: OAuth disabled- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /oauth/token:- post:- operationId: postOAuthToken- tags: [auth]- summary: "[cloud-only] Exchange authorization code or refresh token for a resource-bound access token"- description: |- [cloud-only] OAuth 2.1 token endpoint (RFC 6749 §3.2). Public clients only — `client_secret` is rejected.-- Two grant types are supported:- - `authorization_code` — exchanges the code minted by `/oauth/authorize` (with PKCE verifier) for an access token + first refresh token. Single-use; reuse fails closed.- - `refresh_token` — rotates the refresh token. Old token immediately invalid; presenting an already-rotated token revokes the entire token family and emits a security metric.-- Both grant types re-validate canonical user state, current workspace membership, and the resource's active flag at every mint. A code or refresh token bound to a deactivated resource fails closed.-- Errors follow RFC 6749 §5.2. Logs never contain raw codes, refresh tokens, or minted tokens.-- Per RFC 6749 §5.1, every 200 and 400 response carries `Cache-Control: no-store` and `Pragma: no-cache` so intermediaries cannot cache token-bearing or state-change-reason responses.- x-runtime: [cloud]- security: []- requestBody:- required: true- content:- application/x-www-form-urlencoded:- schema:- type: object- required: [grant_type, client_id]- properties:- grant_type: { type: string, enum: [authorization_code, refresh_token] }- client_id: { type: string }- code: { type: string }- redirect_uri: { type: string }- code_verifier: { type: string }- refresh_token: { type: string }- scope: { type: string }- client_secret: { type: string }- responses:- "200":- description: New token pair- headers:- Cache-Control:- schema:- type: string- description: 'Always "no-store" per RFC 6749 §5.1'- Pragma:- schema:- type: string- description: 'Always "no-cache" per RFC 6749 §5.1'- content:- application/json:- schema:- $ref: "#/components/schemas/OAuthTokenResponse"- "400":- description: RFC 6749 §5.2 error- headers:- Cache-Control:- schema:- type: string- description: 'Always "no-store" per RFC 6749 §5.1'- Pragma:- schema:- type: string- description: 'Always "no-cache" per RFC 6749 §5.1'- content:- application/json:- schema:- $ref: "#/components/schemas/OAuthTokenError"- "404":- description: OAuth disabled- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /oauth/register:- post:- operationId: postOAuthRegister- tags: [auth]- summary: "[cloud-only] Dynamic Client Registration (RFC 7591)"- description: |- [cloud-only] Public, unauthenticated, insert-only RFC 7591 §3.1 client registration. Used by MCP-spec-compliant clients to self-register a public OAuth client without operator involvement.-- Policy:-- - Public clients only — `token_endpoint_auth_method` is forced to `none`. Confidential-client registration is out of scope this phase.- - Server-owned `resource_grants`. Caller-supplied `scope` or `resource_grants` is rejected as `invalid_client_metadata` (would be a privilege-escalation surface). Dynamic clients receive the same scopes the active resource publishes.- - Application-type-aware redirect URI policy. `application_type=native` accepts loopback (`127.0.0.1`, `::1`, `localhost`) and reverse-DNS-shaped custom schemes; `application_type=web` accepts HTTPS to hosts in an operator-controlled allowlist only. `application_type` is REQUIRED on the request — missing or empty rejects with `invalid_client_metadata`.- - Anti-impersonation: reserved client names are rejected from third parties via NFKC-folded compare.- - Generated `client_id` carries a stable prefix to distinguish dynamic from seeded clients in audit logs.- - Cache-Control: `no-store` on every 201 and 400 response (the response carries fresh credentials and rejection reasons).- x-runtime: [cloud]- security: []- requestBody:- required: true- content:- application/json:- schema:- $ref: "#/components/schemas/OAuthRegisterRequest"- responses:- "201":- description: Registered. Body echoes the metadata RFC 7591 §3.2.1 requires.- headers:- Cache-Control:- schema:- type: string- description: 'Always "no-store"'- Pragma:- schema:- type: string- description: 'Always "no-cache"'- content:- application/json:- schema:- $ref: "#/components/schemas/OAuthRegisterResponse"- "400":- description: RFC 7591 §3.2.2 invalid client metadata- headers:- Cache-Control:- schema:- type: string- description: 'Always "no-store"'- Pragma:- schema:- type: string- description: 'Always "no-cache"'- content:- application/json:- schema:- $ref: "#/components/schemas/OAuthRegisterError"- "404":- description: OAuth disabled- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "503":- description: No active resource is configured — DCR cannot mint a usable client until an active resource row is seeded.- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- # ---------------------------------------------------------------------------- # Billing (cloud)- # ---------------------------------------------------------------------------- /api/billing/balance:- get:- operationId: getBillingBalance- tags: [billing]- summary: Get current credit balance- description: "[cloud-only] Returns the authenticated user's current credit balance and usage summary."- x-runtime: [cloud]- responses:- "200":- description: Balance info- content:- application/json:- schema:- $ref: "#/components/schemas/BillingBalanceResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/billing/events:- get:- operationId: getBillingEvents- tags: [billing]- summary: List billing events- description: "[cloud-only] Returns a paginated list of billing events (charges, credits, refunds) for the authenticated user."- x-runtime: [cloud]- parameters:- - name: limit- in: query- schema:- type: integer- description: Maximum number of results- - name: offset- in: query- schema:- type: integer- description: Pagination offset- - name: type- in: query- schema:- type: string- description: Filter by event type- responses:- "200":- description: Billing events- content:- application/json:- schema:- $ref: "#/components/schemas/BillingEventsResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/billing/ops/{id}:- get:- operationId: getBillingOpStatus- tags: [billing]- summary: Get a billing operation by ID- description: "[cloud-only] Returns details of a specific billing operation."- x-runtime: [cloud]- parameters:- - name: id- in: path- required: true- schema:- type: string- description: The billing operation ID.- responses:- "200":- description: Billing operation- content:- application/json:- schema:- $ref: "#/components/schemas/BillingOpStatusResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/billing/payment-portal:- post:- operationId: getPaymentPortal- tags: [billing]- summary: Create a payment portal session- description: "[cloud-only] Creates a Stripe customer portal session for managing payment methods and invoices. Returns a URL to redirect the user to."- x-runtime: [cloud]- responses:- "200":- description: Portal session- content:- application/json:- schema:- type: object- properties:- url:type: string- format: uri- description: Stripe portal URL- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '400':- description: Bad request (e.g., missing return_url)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/billing/plans:- get:- operationId: getBillingPlans- tags: [billing]- summary: List available billing plans- description: "[cloud-only] Returns the list of available subscription plans and their pricing."- x-runtime: [cloud]- responses:- "200":- description: Plan list- content:- application/json:- schema:- type: array- items:- $ref: "#/components/schemas/BillingPlan"-- '401':- description: Unauthorized- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/billing/preview-subscribe:- post:- operationId: previewSubscribe- tags: [billing]- summary: Preview a subscription change- description: "[cloud-only] Returns a preview of what a subscription change would cost, including prorations."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - plan_id- properties:- plan_id:- type: string- description: ID of the plan to preview- responses:- "200":- description: Subscription preview- content:- application/json:- schema:- $ref: "#/components/schemas/PreviewSubscribeResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/billing/status:- get:- operationId: getBillingStatus- tags: [billing]- summary: Get billing status- description: "[cloud-only] Returns the authenticated user's current billing and subscription status."- x-runtime: [cloud]- responses:- "200":- description: Billing status- content:- application/json:- schema:- $ref: "#/components/schemas/BillingStatusResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '404':- description: Workspace not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/billing/subscribe:- post:- operationId: subscribe- tags: [billing]- summary: Subscribe to a billing plan- description: "[cloud-only] Creates a new subscription to the specified billing plan."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - plan_id- properties:- plan_id:- type: string- description: ID of the plan to subscribe to- payment_method_id:- type: string- description: Stripe payment method ID- responses:- "200":- description: Subscription created- content:- application/json:- schema:- $ref: "#/components/schemas/SubscribeResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/billing/subscription/cancel:- post:- operationId: cancelSubscription- tags: [billing]- summary: Cancel the active subscription- description: "[cloud-only] Cancels the authenticated user's active subscription. The subscription remains active until the end of the current billing period."- x-runtime: [cloud]- responses:- "200":- description: Subscription cancelled- content:- application/json:- schema:- $ref: "#/components/schemas/CancelSubscriptionResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '400':- description: Invalid request (e.g., no active subscription)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/billing/subscription/resubscribe:- post:- operationId: resubscribe- tags: [billing]- summary: Resubscribe after cancellation- description: "[cloud-only] Reactivates a subscription that was previously cancelled but has not yet expired."- x-runtime: [cloud]- responses:- "200":- description: Subscription reactivated- content:- application/json:- schema:- $ref: "#/components/schemas/ResubscribeResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '400':- description: Invalid request (e.g., no active subscription, not in cancellation grace period)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/billing/topup:- post:- operationId: createTopup- tags: [billing]- summary: Purchase additional credits- description: "[cloud-only] Purchases a one-time credit top-up using the user's payment method on file."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - amount- properties:- amount:- type: integer- description: Number of credits to purchase- responses:- "200":- description: Top-up successful- content:- application/json:- schema:- $ref: "#/components/schemas/CreateTopupResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # Workspace (cloud)- # ---------------------------------------------------------------------------- /api/workspace/api-keys:- get:- operationId: listWorkspaceAPIKeys- tags: [workspace]- summary: List workspace API keys- description: "[cloud-only] Returns the list of API keys for the current workspace."- x-runtime: [cloud]- responses:- "200":- description: API key list- content:- application/json:- schema:- type: array- items:- $ref: "#/components/schemas/WorkspaceApiKey"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: createWorkspaceAPIKey- tags: [workspace]- summary: Create a workspace API key- description: "[cloud-only] Creates a new API key for the current workspace."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - name- properties:- name:- type: string- description: Display name for the API key- description:- type: string- description: User-provided description of the key's purpose- maxLength: 5000- responses:- "201":- description: API key created- content:- application/json:- schema:- $ref: "#/components/schemas/CreateWorkspaceAPIKeyResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '404':- description: Workspace not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '422':- description: Validation error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '429':- description: Key limit reached- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workspace/api-keys/{id}:- delete:- operationId: revokeWorkspaceAPIKey- tags: [workspace]- summary: Delete a workspace API key- description: "[cloud-only] Revokes and deletes a workspace API key."- x-runtime: [cloud]- parameters:- - name: id- in: path- required: true- schema:- type: string- description: The API key ID.- responses:- "204":- description: API key deleted- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workspace/invites:- get:- operationId: listWorkspaceInvites- tags: [workspace]- summary: List pending workspace invites- description: "[cloud-only] Returns the list of pending invitations for the current workspace."- x-runtime: [cloud]- responses:- "200":- description: Invite list- content:- application/json:- schema:- type: array- items:- $ref: "#/components/schemas/WorkspaceInvite"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: createWorkspaceInvite- tags: [workspace]- summary: Invite a user to the workspace- description: "[cloud-only] Creates an invitation for a user to join the current workspace."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- properties:- email:- type: string- format: email- description: Email address to invite- role:- type: string- enum: [admin, member]- description: Role to assign- responses:- "201":- description: Invite created- content:- application/json:- schema:- $ref: "#/components/schemas/PendingInvite"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "409":- description: Conflict- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '404':- description: Workspace not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '422':- description: Validation error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workspace/invites/{inviteId}:- delete:- operationId: revokeWorkspaceInvite- tags: [workspace]- summary: Cancel a workspace invite- description: "[cloud-only] Cancels a pending workspace invitation."- x-runtime: [cloud]- parameters:- - name: inviteId- in: path- required: true- schema:- type: string- description: The invite ID.- responses:- "204":- description: Invite cancelled- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workspace/leave:- post:- operationId: leaveWorkspace- tags: [workspace]- summary: Leave the current workspace- description: "[cloud-only] Removes the authenticated user from the current workspace."- x-runtime: [cloud]- responses:- "204":- description: Left workspace- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '404':- description: Workspace not found or not a member- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workspace/members:- get:- operationId: listWorkspaceMembers- tags: [workspace]- summary: List workspace members- description: "[cloud-only] Returns the list of members in the current workspace."- x-runtime: [cloud]- responses:- "200":- description: Member list- content:- application/json:- schema:- type: array- items:- $ref: "#/components/schemas/WorkspaceMember"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '404':- description: Workspace not found- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '422':- description: Validation error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workspace/members/{user_id}/api-keys:- get:- operationId: listMemberApiKeys- tags: [workspace]- summary: List API keys for a workspace member- description: "[cloud-only] Returns the API keys belonging to a specific workspace member. Requires admin role."- x-runtime: [cloud]- parameters:- - name: user_id- in: path- required: true- schema:- type: string- description: The member's user ID.- responses:- "200":- description: API key list- content:- application/json:- schema:- type: array- items:- $ref: "#/components/schemas/WorkspaceApiKey"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- delete:- operationId: bulkRevokeWorkspaceMemberAPIKeys- tags: [workspace]- summary: Bulk revoke a member's API keys- description: "[cloud-only] Revokes all active API keys for a specific workspace member. Only workspace owners can perform this action."- x-runtime: [cloud]- parameters:- - name: user_id- in: path- required: true- schema:- type: string- minLength: 1- description: The member's user ID.- responses:- "200":- description: Keys revoked- content:- application/json:- schema:- $ref: "#/components/schemas/BulkRevokeAPIKeysResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden — must be workspace owner- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '422':- description: Validation error (e.g. empty user_id)- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workspace/members/{userId}:- patch:- operationId: updateWorkspaceMember- tags: [workspace]- summary: Update a workspace member's role- description: "[cloud-only] Updates the role of a workspace member. Requires admin role."- x-runtime: [cloud]- parameters:- - name: userId- in: path- required: true- schema:- type: string- description: The member's user ID.- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - role- properties:- role:- type: string- enum: [admin, member]- description: New role to assign- responses:- "200":- description: Member updated- content:- application/json:- schema:- $ref: "#/components/schemas/WorkspaceMember"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- delete:- operationId: removeWorkspaceMember- tags: [workspace]- summary: Remove a member from the workspace- description: "[cloud-only] Removes a member from the current workspace. Requires admin role."- x-runtime: [cloud]- parameters:- - name: userId- in: path- required: true- schema:- type: string- description: The member's user ID.- responses:- "204":- description: Member removed- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workspaces:- get:- operationId: listWorkspaces- tags: [workspace]- summary: List workspaces the user belongs to- description: "[cloud-only] Returns the list of workspaces the authenticated user is a member of."- x-runtime: [cloud]- responses:- "200":- description: Workspace list- content:- application/json:- schema:- type: array- items:- $ref: "#/components/schemas/Workspace"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '404':- description: Feature not enabled for user- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: createWorkspace- tags: [workspace]- summary: Create a new workspace- description: "[cloud-only] Creates a new workspace. The authenticated user becomes the owner."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - name- properties:- name:- type: string- description: Workspace name- responses:- "201":- description: Workspace created- content:- application/json:- schema:- $ref: "#/components/schemas/Workspace"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '404':- description: Feature not enabled for user- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '422':- description: Validation error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/workspaces/{id}:- get:- operationId: getWorkspace- tags: [workspace]- summary: Get a workspace by ID- description: "[cloud-only] Returns details of a workspace the user is a member of."- x-runtime: [cloud]- parameters:- - name: id- in: path- required: true- schema:- type: string- description: The workspace ID.- responses:- "200":- description: Workspace detail- content:- application/json:- schema:- $ref: "#/components/schemas/Workspace"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- patch:- operationId: updateWorkspace- tags: [workspace]- summary: Update workspace settings- description: "[cloud-only] Updates the name or settings of a workspace. Requires admin role."- x-runtime: [cloud]- parameters:- - name: id- in: path- required: true- schema:- type: string- description: The workspace ID.- requestBody:- required: true- content:- application/json:- schema:- type: object- properties:- name:- type: string- description: New workspace name- responses:- "200":- description: Workspace updated- content:- application/json:- schema:- $ref: "#/components/schemas/Workspace"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '422':- description: Validation error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- delete:- operationId: deleteWorkspace- tags: [workspace]- summary: Delete a workspace- description: "[cloud-only] Soft-deletes a workspace. Requires owner role. Personal workspaces cannot be deleted."- x-runtime: [cloud]- parameters:- - name: id- in: path- required: true- schema:- type: string- description: The workspace ID.- responses:- "204":- description: Workspace deleted- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "403":- description: Forbidden — must be workspace owner- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- # ---------------------------------------------------------------------------- # User / settings / misc (cloud)- # ---------------------------------------------------------------------------- /api/feedback:- post:- operationId: submitFeedback- tags: [user]- summary: Submit user feedback- description: "[cloud-only] Submits feedback from the user about their experience with the cloud runtime."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- $ref: "#/components/schemas/FeedbackRequest"- responses:- "201":- description: Feedback submitted- content:- application/json:- schema:- type: object- properties:- id:- type: string- status:- type: string- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/files/mask-layers:- get:- operationId: getMaskLayers- tags: [assets]- summary: Get related mask layer filenames- description: "[cloud-only] Given a mask file (any of the 4 layers), returns all related mask layer filenames. Used by the mask editor to load the paint, mask, and painted layers when reopening a previously edited mask."- x-runtime: [cloud]- parameters:- - name: filename- in: query- required: true- schema:- type: string- description: Hash filename of any mask layer file- responses:- "200":- description: Related mask layers- content:- application/json:- schema:- type: object- properties:- mask:- type: string- description: Filename of the mask layer- nullable: true- paint:+ 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- description: Filename of the paint strokes layer- nullable: true- painted:+ 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 messagetype: string- description: Filename of the painted image layer- nullable: true- painted_masked:+ exception_type:+ description: Python exception type (e.g., "RuntimeError")type: string- description: Filename of the final composite layer- nullable: true- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: File not found or not a mask file- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /api/internal/cloud_analytics:- post:- operationId: postCloudAnalytics- tags: [internal]- summary: Post client analytics events- description: "[cloud-only] Receives analytics events from the frontend for processing by the cloud analytics pipeline."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:- - events- properties:- events:- type: array- items:+ 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 feedbacktype: object- required:- - event_name+ 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 subgraphproperties:- event_name:- type: string- timestamp:- type: string- format: date-time- properties:- type: object- additionalProperties: true- responses:- "200":- description: Events accepted- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/invites/{token}/accept:- post:- operationId: acceptWorkspaceInvite- tags: [workspace]- summary: Accept a workspace invitation- description: "[cloud-only] Accepts a workspace invitation using the invite token. The authenticated user is added to the workspace."- x-runtime: [cloud]- parameters:- - name: token- in: path- required: true- schema:- type: string- description: The invitation token.- responses:- "200":- description: Invite accepted- content:- application/json:- schema:- $ref: "#/components/schemas/AcceptInviteResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '403':- description: Email does not match invite- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '409':- description: Already a member of this workspace- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/secrets:- get:- operationId: listSecrets- tags: [settings]- summary: List user secrets- description: "[cloud-only] Returns the list of secrets (API keys for third-party services) stored for the authenticated user. Secret values are redacted."- x-runtime: [cloud]- responses:- "200":- description: Secret list- content:- application/json:- schema:- type: array- items:- $ref: "#/components/schemas/SecretMeta"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '503':- description: Service unavailable - feature is disabled- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: createSecret- tags: [settings]- summary: Create or update a secret- description: "[cloud-only] Stores a new secret or updates an existing one. Secrets are encrypted at rest."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- required:+ 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- - value- properties:+ - 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: objectname:- type: string- description: Secret name (unique per user)- value:- type: string- description: Secret value- responses:- "201":- description: Secret created- content:- application/json:- schema:- $ref: "#/components/schemas/SecretResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '409':- description: Conflict - secret with this name or provider already exists- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '422':- description: Validation error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '503':- description: Service unavailable - secrets feature disabled- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/secrets/{id}:- get:- operationId: getSecret- tags: [settings]- summary: Get secret metadata- description: "[cloud-only] Returns metadata for a specific secret. Does not return the plaintext secret value."- x-runtime: [cloud]- parameters:- - name: id- in: path- required: true- schema:- type: string- format: uuid- description: The secret ID.- responses:- "200":- description: Secret metadata- content:- application/json:- schema:- $ref: "#/components/schemas/SecretResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '403':- description: Forbidden - user does not own this secret- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '503':- description: Service unavailable - secrets feature disabled- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- patch:- operationId: updateSecret- tags: [settings]- summary: Update a secret- description: "[cloud-only] Updates an existing secret's name and/or value. Both fields are optional; only provided fields are updated."- x-runtime: [cloud]- parameters:- - name: id- in: path- required: true- schema:- type: string- format: uuid- description: The secret ID.- requestBody:- required: true- content:- application/json:- schema:- $ref: "#/components/schemas/UpdateSecretRequest"- responses:- "200":- description: Secret updated- content:- application/json:- schema:- $ref: "#/components/schemas/SecretResponse"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "409":- description: Conflict — a secret with this name already exists- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '403':- description: Forbidden - user does not own this secret- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '503':- description: Service unavailable - secrets feature disabled- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- delete:- operationId: deleteSecret- tags: [settings]- summary: Delete a secret- description: "[cloud-only] Permanently deletes a stored secret."- x-runtime: [cloud]- parameters:- - name: id- in: path- required: true- schema:- type: string- description: The secret ID.- responses:- "204":- description: Secret deleted- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '403':- description: Forbidden - user does not own this secret- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '503':- description: Service unavailable - secrets feature disabled- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/user:- get:- operationId: getUser- tags: [user]- summary: Get the authenticated cloud user- description: "[cloud-only] Returns the profile and account information for the currently authenticated user."- x-runtime: [cloud]- responses:- "200":- description: User profile- content:- application/json:- schema:- $ref: "#/components/schemas/UserResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- put:- operationId: updateCloudUser- tags: [user]- summary: Update the authenticated cloud user profile- description: "[cloud-only] Updates the profile information for the currently authenticated user."- x-runtime: [cloud]- requestBody:- required: true- content:- application/json:- schema:- type: object- properties:- display_name:- type: string- avatar_url:- type: string- format: uri- responses:- "200":- description: Updated profile- content:- application/json:- schema:- $ref: "#/components/schemas/CloudUser"- "400":- description: Bad request- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /api/userdata/{file}/publish:- get:- operationId: getUserdataFilePublish- tags: [userdata]- summary: Get publish info for a userdata file- description: "[cloud-only] Returns the publish status and share info for a userdata workflow file."- x-runtime: [cloud]- parameters:- - name: file- in: path- required: true- schema:- type: string- description: File path relative to user data directory- responses:- "200":- description: Publish info (publish_time is null if never published)- content:- application/json:- schema:- $ref: "#/components/schemas/WorkflowPublishInfo"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Workflow not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- post:- operationId: postUserdataFilePublish- tags: [userdata]- summary: Publish a userdata file to the cloud- description: "[cloud-only] Makes a userdata file available via a public URL for sharing or embedding."- x-runtime: [cloud]- parameters:- - name: file- in: path- required: true- schema:- type: string- description: File path relative to user data directory- responses:- "200":- description: Published file URL- content:- application/json:- schema:- type: object- properties:- url:+ description: Display name of the subgraph blueprinttype: string- format: uri- description: Public URL of the published file- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '400':- description: Bad request- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/vhs/queryvideo:- get:- operationId: getVhsQueryVideo- tags: [view]- summary: Query VHS video metadata- description: "[cloud-only] Returns metadata about a video file processed by the VHS (Video Helper Suite) integration."- x-runtime: [cloud]- parameters:- - name: filename- in: query- required: true- schema:- type: string- description: Video filename- - name: type- in: query- schema:- type: string- enum: [input, output, temp]- description: Directory type- - name: subfolder- in: query- schema:- type: string- description: Subfolder within the directory- responses:- "200":- description: Video metadata- content:- application/json:- schema:- type: object- additionalProperties: true- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '400':- description: 'Missing required query parameter. Produced by the oapi-codegen- wrapper via echo.NewHTTPError, so the body shape matches Echo''s- default HTTPError serialization rather than ErrorResponse.- '- content:- application/json:- schema:- $ref: '#/components/schemas/BindingErrorResponse'- /api/vhs/viewaudio:- get:- operationId: viewVhsAudio- tags: [view]- summary: View or download VHS audio- description: "[cloud-only] Returns audio content from a VHS-processed file."- x-runtime: [cloud]- parameters:- - name: filename- in: query- required: true- schema:- type: string- description: Audio filename- - name: type- in: query- schema:- type: string- enum: [input, output, temp]- description: Directory type- - name: subfolder- in: query- schema:- type: string- description: Subfolder within the directory- responses:- "200":- description: Audio content- content:- audio/*:- schema:- type: string- format: binary- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /api/vhs/viewvideo:- get:- operationId: viewVhsVideo- tags: [view]- summary: View or download VHS video- description: "[cloud-only] Returns video content from a VHS-processed file."- x-runtime: [cloud]- parameters:- - name: filename- in: query- required: true- schema:- type: string- description: Video filename- - name: type- in: query- schema:- type: string- enum: [input, output, temp]- description: Directory type- - name: subfolder- in: query- schema:- type: string- description: Subfolder within the directory- responses:- "200":- description: Video content- content:- video/*:- schema:- type: string- format: binary- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /api/viewvideo:- get:- operationId: viewVideo- tags: [view]- summary: View or download a video file- deprecated: true- description: |- **Deprecated.** This endpoint is an alias of `GET /api/view` added for- legacy history-queue video playback. Callers should use `/api/view`- directly; the endpoint is retained for backward compatibility but will- be removed in a future release.- x-runtime: [cloud]- parameters:- - name: filename- in: query- required: true- schema:- type: string- description: Video filename- - name: type- in: query- schema:- type: string- enum: [input, output, temp]- description: Directory type- - name: subfolder- in: query- schema:- type: string- description: Subfolder within the directory- responses:- "200":- description: Video content- content:- video/*:- schema:- type: string- format: binary- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- /api/tasks:- get:- operationId: listTasks- tags: [task]- summary: List background tasks- description: "[cloud-only] Retrieve a paginated list of background tasks for the authenticated user. Supports filtering by task type, status, and creation time."- x-runtime: [cloud]- parameters:- - name: task_name- in: query- schema:- type: string- description: Filter by task type name (exact match).- - name: idempotency_key- in: query- schema:- type: string- description: Filter by idempotency key (exact match).- - name: status- in: query- schema:- type: string- description: Filter by one or more statuses (comma-separated).- - name: created_after- in: query- schema:- type: string- format: date-time- description: Filter tasks created after this timestamp.- - name: created_before- in: query- schema:- type: string- format: date-time- description: Filter tasks created before this timestamp.- - name: sort_order- in: query- schema:- type: string- enum: [asc, desc]- default: desc- description: Sort direction by create_time.- - name: offset- in: query- schema:- type: integer- minimum: 0- default: 0- description: Pagination offset (0-based).- - name: limit- in: query- schema:- type: integer- minimum: 1- maximum: 100- default: 20- description: Maximum items per page (1-100).- responses:- "200":- description: Tasks retrieved- content:- application/json:- schema:- $ref: "#/components/schemas/TasksListResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "422":- description: Validation error- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- /api/tasks/{task_id}:- get:- operationId: getTask- tags: [task]- summary: Get task details- description: "[cloud-only] Retrieve full details for a specific background task."- x-runtime: [cloud]- parameters:- - name: task_id- in: path- required: true- schema:- type: string- format: uuid- description: Task identifier (UUID).- responses:- "200":- description: Task details- content:- application/json:- schema:- $ref: "#/components/schemas/TaskResponse"- "401":- description: Unauthorized- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"- "404":- description: Task not found- content:- application/json:- schema:- $ref: "#/components/schemas/CloudError"-- '500':- description: Internal server error- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'-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- description: A workflow submission. Wraps the prompt graph plus optional client identifier and extra per-request data.- 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)- workflow_id:- type: string- format: uuid- nullable: true- x-runtime: [cloud]- description: "[cloud-only] Cloud workflow entity ID for tracking and gallery association. Ignored by local ComfyUI."- workflow_version_id:- type: string- format: uuid- nullable: true- x-runtime: [cloud]- description: "[cloud-only] Cloud workflow version ID for pinning execution to a specific version. Ignored by local ComfyUI."-- PromptResponse:- type: object- description: Server acknowledgement of a workflow submission. Includes the assigned `prompt_id` and current queue position.- 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- description: Summary of a queued or recently-executed prompt, as returned by the queue and history endpoints.- 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+ 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: |- 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-- QueueManageResponse:- type: object- x-runtime: [cloud]- description: >-- [cloud-only] Result of a queue mutation. The Cloud runtime returns which- items were deleted and whether the queue was cleared; local ComfyUI- returns an empty 200 body.- properties:- deleted:- type: array- nullable: true- items:- type: string- description: Prompt IDs that were deleted from the queue.- cleared:- type: boolean- nullable: true- description: Whether the queue was cleared.-- # -------------------------------------------------------------------- # 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- enum:- - pending- - in_progress- - completed- - failed- - cancelled- description: Current job status- create_time:- type: integer- format: int64- description: Job creation timestamp (Unix milliseconds).- execution_start_time:- type: integer- format: int64- description: Workflow execution start timestamp (Unix milliseconds, terminal states only).- execution_end_time:- type: integer- format: int64- description: Workflow execution end timestamp (Unix milliseconds, terminal states only).- preview_output:- type: object- additionalProperties: true- description: Primary preview output- outputs_count:- type: integer- description: Total number of output files- workflow_id:- type: string- nullable: true- x-runtime: [cloud]- description: "[cloud-only] UUID of the Cloud workflow entity this job is associated with. Local ComfyUI returns null."- execution_error:- x-runtime: [cloud]- description: "[cloud-only] Detailed execution error from ComfyUI for failed jobs. Absent on local ComfyUI."- allOf:- - $ref: "#/components/schemas/ExecutionError"-- JobDetailResponse:- type: object- description: Full job details including workflow and outputs- required:- - id- - status- properties:- id:- type: string- format: uuid- status:- type: string- enum:- - pending- - in_progress- - completed- - failed- - cancelled- 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: integer- format: int64- description: Job creation timestamp (Unix milliseconds).- update_time:- type: integer- format: int64- description: Last state-change timestamp (Unix milliseconds).- execution_start_time:- type: integer- format: int64- description: Workflow execution start timestamp (Unix milliseconds, terminal states only).- execution_end_time:- type: integer- format: int64- description: Workflow execution end timestamp (Unix milliseconds, terminal states only).- 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- description: Pagination metadata returned alongside list responses.- properties:- offset:- type: integer- limit:- type: integer- total:- type: integer- has_more:- type: boolean-- # -------------------------------------------------------------------- # Upload / View- # -------------------------------------------------------------------- UploadResult:- type: object- description: Response body returned by the image/mask upload endpoints, describing where the uploaded file now lives.- 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- nullable: true- description: |- Device index within its type (e.g. CUDA ordinal for `cuda:0`,- `cuda:1`). `null` for devices with no index, including the CPU- device returned in `--cpu` mode (PyTorch's `torch.device('cpu').index`- is `None`).- 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- description: Hardware, VRAM, Python, and ComfyUI version information for the running process.- 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- comfy_package_versions:- type: array- description: Installed and required versions for every comfy* package pinned in requirements.txt- items:- type: object- required:- - name- - installed- - required- properties:- name:- type: string- installed:+ 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 executiontype: string- nullable: true- required:+ status:+ additionalProperties: true+ description: Execution status and timeline information+ type: object+ workflow_id:+ description: UUID identifying the workflow graph definitiontype: string- nullable: true- devices:- type: array- items:- $ref: "#/components/schemas/DeviceStats"-- # -------------------------------------------------------------------- # Node / Object Info- # -------------------------------------------------------------------- NodeInfo:- type: object- description: 'Definition of a registered node class: its inputs, outputs, category, and display metadata.'- 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- nullable: true- description: |- Category override used by the essentials pack. The- `essentials_category` key may be present with a string value,- present and `null`, or absent entirely:-- - V1 nodes: `essentials_category` is **omitted** when the node- class doesn't define an `ESSENTIALS_CATEGORY` attribute, and- **`null`** if the attribute is explicitly set to `None`.- - V3 nodes (`comfy_api.latest.io`): `essentials_category` is- **always present**, and **`null`** for nodes whose `Schema`- doesn't populate it.-- # -------------------------------------------------------------------- # Models- # -------------------------------------------------------------------- ModelFolder:- type: object- description: A configured model folder and the list of disk paths it resolves to.- 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- description: A single model file in a folder, with filesystem metadata.- 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:- description: |- Response body for the POST endpoints `/api/userdata/{file}` and- `/api/userdata/{file}/move/{dest}`. Returns a single item whose- shape depends on the `full_info` query parameter.- x-variant-selector:- full_info=true: file-info object (`GetUserDataResponseFullFile`)- default: relative path string- oneOf:- - $ref: "#/components/schemas/GetUserDataResponseFullFile"- - type: string- description: Relative path of the written or moved file. Returned when `full_info` is absent or false.-- ListUserdataResponse:- description: |- Response body for `GET /api/userdata`. The array item shape is- determined by the `full_info` and `split` query parameters.- x-variant-selector:- full_info=true: array of file-info objects (`GetUserDataResponseFullFile`)- split=true: array of `[relative_path, ...path_components]` arrays- default: array of relative path strings- oneOf:- - type: array- items:- $ref: "#/components/schemas/GetUserDataResponseFullFile"- description: Returned when `full_info=true`.- - type: array- items:- type: array- items:- type: string- minItems: 2- description: |- Returned when `split=true` and `full_info=false`. Each inner- array is `[relative_path, ...path_components]`.- - type: array- items:- type: string- description: Default shape — array of file paths relative to the user data root.-- GetUserDataResponseFullFile:- type: object- description: A single entry in a full-info user data listing.- 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- description: A registered asset — an input/output file tracked in the asset database with content hash and metadata.- 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- hash:- type: string- nullable: true- description: Blake3 content hash of the asset (preferred over asset_hash)- pattern: "^blake3:[a-f0-9]{64}$"- asset_hash:- type: string- nullable: true- deprecated: true- description: "Deprecated: use `hash` instead. 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- nullable: true- deprecated: true- description: "Deprecated: use job_id instead. ID of the prompt that created this asset."- job_id:- type: string- format: uuid- nullable: true- description: ID of the job 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:- description: Response body returned after successfully registering a new asset.- 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- description: Response body returned after updating an asset's metadata.- required:- - id- - updated_at- properties:- id:- type: string- format: uuid- name:- type: string- hash:- type: string- nullable: true- description: Blake3 content hash of the asset (preferred over asset_hash)- pattern: "^blake3:[a-f0-9]{64}$"- asset_hash:- type: string- nullable: true- deprecated: true- description: "Deprecated: use `hash` instead. Blake3 hash of the asset content."- pattern: "^blake3:[a-f0-9]{64}$"- tags:- type: array- items:- type: string- mime_type:- type: string- user_metadata:- type: object- additionalProperties: true- prompt_id:- type: string- format: uuid- nullable: true- deprecated: true- description: "Deprecated: use job_id instead. ID of the prompt that created this asset."- job_id:- type: string- format: uuid- nullable: true- description: ID of the job that created this asset- updated_at:- type: string- format: date-time-- ListAssetsResponse:- type: object- description: Paginated list of assets.- required:- - assets- - total- - has_more- properties:- assets:- type: array- items:- $ref: "#/components/schemas/Asset"- total:- type: integer- has_more:- type: boolean-- TagInfo:- type: object- description: A tag known to the asset database, with the number of assets bearing it.- required:- - name- - count- properties:- name:- type: string- count:- type: integer-- ListTagsResponse:- type: object- description: Flat list of all tags, with counts.- required:- - tags- - total- - has_more- properties:- tags:- type: array- items:- $ref: "#/components/schemas/TagInfo"- total:- type: integer- has_more:- type: boolean-- AssetTagHistogramResponse:- type: object- description: Tags that would refine a filtered asset query, with the count of assets each tag would additionally select.- required:- - tag_counts- properties:- tag_counts:- type: object- additionalProperties:- type: integer- description: Map of tag names to occurrence counts-- TagsModificationResponse:- type: object- description: Response body returned after adding or removing tags on an asset.- 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-- 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-- StatusWsMessageStatus:- type: object- description: Inner payload of a `status` WebSocket message, describing the execution queue state.- 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-- # -------------------------------------------------------------------- # Cloud-runtime schemas- #- # These schemas are exclusively referenced by cloud-runtime operations.- # Tagged x-runtime: [cloud].- # -------------------------------------------------------------------- CloudError:- type: object- x-runtime: [cloud]- description: "[cloud-only] Standard error response from cloud endpoints."- required:- - error- properties:- error:- type: string- description: Error message- code:- type: string- description: Machine-readable error code- details:- type: object- additionalProperties: true- description: Additional error context-- CloudJobStatus:- type: object- x-runtime: [cloud]- description: "[cloud-only] Status of a cloud job."- required:- - id- - status- properties:- id:- type: string- format: uuid- status:- type: string- enum: [pending, running, completed, failed, cancelled]- progress:- type: number- minimum: 0- maximum: 1- description: "Execution progress (0.0 to 1.0)"- started_at:- type: string- format: date-time- nullable: true- completed_at:- type: string- format: date-time- nullable: true-- CloudPrompt:- type: object- x-runtime: [cloud]- description: "[cloud-only] A cloud-executed prompt record."- required:- - id- - status- properties:- id:- type: string- format: uuid- status:- type: string- workflow:- type: object- additionalProperties: true- outputs:- type: object- additionalProperties: true- created_at:- type: string- format: date-time- completed_at:- type: string- format: date-time- nullable: true-- HistoryV2Response:- type: object- x-runtime: [cloud]- description: "[cloud-only] Paginated execution history in v2 format."- required:- - items- - total- - has_more- properties:- items:- type: array- items:- $ref: "#/components/schemas/HistoryV2Entry"- total:- type: integer- has_more:- type: boolean-- HistoryV2Entry:- type: object- x-runtime: [cloud]- description: "[cloud-only] A single execution history entry in v2 format."- required:- - id- - status- properties:- id:- type: string- format: uuid- status:- type: string- workflow:- type: object- additionalProperties: true- outputs:- type: object- additionalProperties: true- created_at:- type: string- format: date-time- started_at:- type: string- format: date-time- nullable: true- completed_at:- type: string- format: date-time- nullable: true- preview_output:- type: object- additionalProperties: true-- CloudLogsResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] Paginated cloud execution logs."- required:- - entries- properties:- entries:- type: array- items:+ required:+ - prompt_idtype: object+ HistoryManageRequest:+ additionalProperties: false+ description: Request to manage history operationsproperties:- timestamp:- type: string- format: date-time- level:- type: string- enum: [debug, info, warn, error]- message:- type: string- job_id:- type: string- format: uuid- total:- type: integer- has_more:- type: boolean-- AssetDownloadRequest:- type: object- x-runtime: [cloud]- description: "[cloud-only] A single asset to download to the cloud runtime."- required:- - asset_id- properties:- asset_id:- type: string- format: uuid- description: ID of the asset to download- target_path:- type: string- description: Target path on the runtime filesystem-- ImportPublishedAssetsRequest:- type: object- x-runtime: [cloud]- description: "[cloud-only] Request body for importing published assets into the caller's library."- required:- - published_asset_ids- properties:- published_asset_ids:- type: array- description: IDs of published assets (inputs and models) to import.- items:- type: string- share_id:- type: string- nullable: true- description: |- Optional. Share ID of the published workflow these assets belong to. When provided (non-null, non-empty): all `published_asset_ids` must belong to this share's workflow version; returns 400 if the share is not found or any asset does not belong to it. When omitted, null, or empty string: no share-scoped validation is performed and the assets are validated only against global rules (preserved for clients that have not yet adopted `share_id`).-- ImportPublishedAssetsResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] Response after importing published assets. Each returned `AssetInfo.id` is the caller's newly-created private asset ID, not the published asset ID supplied in the request."- required:- - assets- properties:- assets:- type: array- items:- $ref: "#/components/schemas/AssetInfo"-- RemoteAssetMetadata:- type: object- x-runtime: [cloud]- description: "[cloud-only] Metadata fetched from a remote asset URL."- properties:- content_type:- type: string- description: MIME type of the remote file- content_length:- type: integer- format: int64- description: Size in bytes- filename:- type: string- description: Suggested filename from Content-Disposition or URL-- CloudNode:- type: object- x-runtime: [cloud]- description: "[cloud-only] An installed custom node package in the cloud runtime."- required:- - id- - name- properties:- id:- type: string- name:- type: string- version:- type: string- description:- type: string- author:- type: string- repository:- type: string- format: uri- installed_at:- type: string- format: date-time- enabled:- type: boolean-- HubLabel:- type: object- x-runtime: [cloud]- description: "[cloud-only] A label/category used for tagging hub content."- required:- - id- - name- properties:- id:- type: string- name:- type: string- description:- type: string- color:- type: string- description: Hex color code for the label-- HubProfile:- type: object- x-runtime: [cloud]- description: "[cloud-only] A public user profile on the ComfyUI Hub."- required:- - username- properties:- username:- type: string- display_name:- type: string- bio:- type: string- avatar_url:- type: string- format: uri- links:- type: array- items:- type: string- format: uri- workflow_count:- type: integer- created_at:- type: string- format: date-time-- HubWorkflow:- type: object- x-runtime: [cloud]- description: "[cloud-only] A published workflow on the ComfyUI Hub."- required:- - share_id- - name- properties:- share_id:- type: string- name:- type: string- description:- type: string- author:- $ref: "#/components/schemas/HubProfile"- labels:- type: array- items:- $ref: "#/components/schemas/HubLabel"- thumbnail_url:- type: string- format: uri- content:- type: object- additionalProperties: true- description: Workflow graph JSON- likes:- type: integer- views:- type: integer- forks:- type: integer- created_at:- type: string- format: date-time- updated_at:- type: string- format: date-time-- HubWorkflowList:- type: object- x-runtime: [cloud]- description: "[cloud-only] Paginated list of hub workflows."- required:- - workflows- - total- - has_more- properties:- workflows:- type: array- items:- $ref: "#/components/schemas/HubWorkflow"- total:- type: integer- has_more:- type: boolean-- HubWorkflowIndexEntry:- type: object- x-runtime: [cloud]- description: "[cloud-only] Lightweight entry in the hub workflow index for client-side search."- required:- - share_id- - name- properties:- share_id:- type: string- name:- type: string- author_username:- type: string- labels:- type: array- items:- type: string- likes:- type: integer- updated_at:- type: string- format: date-time-- CloudWorkflow:- type: object- x-runtime: [cloud]- description: "[cloud-only] A cloud-managed workflow with version history."- required:- - id- - name- properties:- id:- type: string- format: uuid- name:- type: string- description:- type: string- share_id:- type: string- nullable: true- description: Public share identifier if published- latest_version_id:- type: string- format: uuid- nullable: true- thumbnail_url:- type: string- format: uri- nullable: true- created_at:- type: string- format: date-time- updated_at:- type: string- format: date-time-- CloudWorkflowList:- type: object- x-runtime: [cloud]- description: "[cloud-only] Paginated list of cloud workflows."- required:- - workflows- - total- - has_more- properties:- workflows:- type: array- items:- $ref: "#/components/schemas/CloudWorkflow"- total:- type: integer- has_more:- type: boolean-- CloudWorkflowVersion:- type: object- x-runtime: [cloud]- description: "[cloud-only] A version of a cloud workflow."- required:- - id- - workflow_id- properties:- id:- type: string- format: uuid- workflow_id:- type: string- format: uuid- version_number:- type: integer- created_at:- type: string- format: date-time-- AuthSession:- type: object- x-runtime: [cloud]- description: "[cloud-only] Current authentication session state."- required:- - user- properties:- user:- $ref: "#/components/schemas/CloudUser"- workspace:- $ref: "#/components/schemas/Workspace"- expires_at:- type: string- format: date-time-- AuthTokenResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] OAuth2 token response."- required:- - access_token- - token_type- properties:- access_token:- type: string- token_type:- type: string- description: Always "Bearer"- expires_in:- type: integer- description: Token lifetime in seconds- refresh_token:- type: string- nullable: true- scope:- type: string-- JwksResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] JSON Web Key Set for JWT verification."- required:- - keys- properties:- keys:- type: array- items:+ 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: arraytype: object- required:- - kty- - kid- - use+ 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:- kty:- type: string- description: Key type (e.g. RSA)- kid:- type: string- description: Key ID- use:- type: string- description: Key use (e.g. sig)- alg:- type: string- description: Algorithm (e.g. RS256)- n:- type: string- description: RSA modulus (base64url)- e:- type: string- description: RSA exponent (base64url)- additionalProperties: true-- OAuthAuthorizationServerMetadata:- type: object- x-runtime: [cloud]- description: "[cloud-only] OAuth 2.1 authorization-server metadata (RFC 8414)."- required:- - issuer- - authorization_endpoint- - token_endpoint- - jwks_uri- - response_types_supported- - grant_types_supported- - code_challenge_methods_supported- - token_endpoint_auth_methods_supported- properties:- issuer:- type: string- format: uri- authorization_endpoint:- type: string- format: uri- token_endpoint:- type: string- format: uri- jwks_uri:- type: string- format: uri- registration_endpoint:- type: string- format: uri- description: "[cloud-only] RFC 7591 §3.1 Dynamic Client Registration endpoint. Advertised so MCP-spec-compliant clients can auto-discover and self-register without operator involvement. Present only when DCR is enabled."- response_types_supported:- type: array- items:- type: string- grant_types_supported:- type: array- items:- type: string- code_challenge_methods_supported:- type: array- items:- type: string- token_endpoint_auth_methods_supported:- type: array- items:- type: string- scopes_supported:- type: array- items:- type: string-- OAuthProtectedResourceMetadata:- type: object- x-runtime: [cloud]- description: "[cloud-only] OAuth 2.1 protected-resource metadata (RFC 9728)."- required:- - resource- - authorization_servers- - scopes_supported- properties:- resource:- type: string- format: uri- authorization_servers:- type: array- items:- type: string- format: uri- scopes_supported:- type: array- items:- type: string- bearer_methods_supported:- type: array- items:- type: string-- OAuthConsentChallenge:- type: object- x-runtime: [cloud]- description: "[cloud-only] Server-side state describing the OAuth consent decision the user is being asked to make. Returned by GET /oauth/authorize when a valid session exists; the frontend renders the consent UI from this payload and POSTs the decision back. Browser never sees the original OAuth params on resume."- required:- - oauth_request_id- - csrf_token- - client_display_name- - resource_display_name- - scopes- - workspaces- properties:- oauth_request_id:- type: string- format: uuid- description: Opaque server-side identifier for the authorization-request row. Carried back unchanged in the consent submission.- csrf_token:- type: string- description: Per-row CSRF token bound to this authorization request (not to the session). Must be echoed back on POST.- client_display_name:- type: string- description: Human-readable name of the OAuth client requesting authorization.- resource_display_name:- type: string- description: Human-readable name of the protected resource.- scopes:- type: array- description: Scopes the client is requesting for this resource. The frontend should present these for the user to approve.- items:- type: string- workspaces:- type: array- description: Workspaces the user can select from. Membership is re-checked on POST.- items:- $ref: "#/components/schemas/OAuthConsentChallengeWorkspace"-- OAuthConsentChallengeWorkspace:- type: object- x-runtime: [cloud]- description: "[cloud-only] One workspace option presented in the OAuth consent challenge."- required: [id, name, type, role]- properties:- id: { type: string }- name: { type: string }- type: { type: string, enum: [personal, team] }- role: { type: string, enum: [owner, member] }-- OAuthAuthorizeRedirectResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] Redirect target produced after a JSON consent submission. The frontend must navigate the browser to this URL so custom-scheme client callbacks work without relying on fetch-visible 302 headers."- required:- - redirect_url- properties:- redirect_url:- type: string- format: uri- description: OAuth client redirect URI with either code+state for allow, or error+state for deny.-- OAuthTokenResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] RFC 6749 §5.1 successful token response."- required: [access_token, token_type, expires_in, refresh_token, scope]- properties:- access_token:- type: string- description: Resource-bound access token (audience matches the protected resource).- token_type:- type: string- enum: [Bearer]- expires_in:- type: integer- description: Access token lifetime in seconds.- refresh_token:- type: string- description: Opaque refresh token. Rotates on every successful refresh; presenting an already-rotated token revokes the entire family.- scope:- type: string- description: Space-delimited scopes granted with this token.-- OAuthTokenError:- type: object- x-runtime: [cloud]- description: "[cloud-only] RFC 6749 §5.2 error response."- required: [error]- properties:- error:- type: string- description: 'RFC 6749 §5.2 error code: invalid_request, invalid_client, invalid_grant, unauthorized_client, unsupported_grant_type, invalid_scope.'- error_description:- type: string- description: Human-readable, no leak of internal storage state.-- OAuthRegisterRequest:- type: object- x-runtime: [cloud]- additionalProperties: false- description: "[cloud-only] RFC 7591 §2 client metadata document. Only the fields the server honors are listed; presence of `scope` or `resource_grants` in the request is rejected (`invalid_client_metadata`) because those are server-owned for dynamic clients."- required:- - redirect_uris- - application_type- properties:- redirect_uris:- type: array- items:- type: string- minItems: 1- maxItems: 5- description: 1–5 redirect URIs. Validated against `application_type` policy.- client_name:- type: string- maxLength: 100- description: Human-readable name shown in the consent UI. Reserved-name list rejects impersonation of major clients.- application_type:- type: string- enum: [native, web]- description: |- RFC 7591 §2 application_type. **REQUIRED** — clients MUST declare intent; the server does not default this field. `native` for desktop / CLI / MCP-spec-strict clients (loopback redirects); `web` for hosted clients (HTTPS only, host must be allowlisted). A missing or explicitly empty `application_type` rejects with `invalid_client_metadata`.- token_endpoint_auth_method:- type: string- enum: [none]- description: 'Public clients only this phase — must be `none` if present. The server forces `none` regardless.'- grant_types:- type: array- items:- type: string- enum: [authorization_code, refresh_token]- description: Optional. Defaults to `["authorization_code","refresh_token"]`.- response_types:- type: array- items:- type: string- enum: [code]- description: Optional. Defaults to `["code"]`.- scope:- type: string- nullable: true- description: "**REJECTED IF PRESENT.** Dynamic clients do not pick scopes — the server assigns scopes from the active resource's published list. Sending `scope` in the registration body is treated as a privilege-escalation attempt and returns `invalid_client_metadata`."- resource_grants:- type: object- nullable: true- additionalProperties:- type: array- items:- type: string- description: "**REJECTED IF PRESENT.** Same reason as `scope`. The set of resources and scopes a dynamic client may request is server-policy, not request-driven."- client_uri:- type: string- nullable: true- description: "**REJECTED IF PRESENT.** Unsupported RFC 7591 metadata for this public-client phase."- logo_uri:- type: string- nullable: true- description: "**REJECTED IF PRESENT.** Unsupported RFC 7591 metadata for this public-client phase."- tos_uri:- type: string- nullable: true- description: "**REJECTED IF PRESENT.** Unsupported RFC 7591 metadata for this public-client phase."- policy_uri:- type: string- nullable: true- description: "**REJECTED IF PRESENT.** Unsupported RFC 7591 metadata for this public-client phase."- software_id:- type: string- nullable: true- description: "**REJECTED IF PRESENT.** Unsupported RFC 7591 metadata for this public-client phase."- software_version:- type: string- nullable: true- description: "**REJECTED IF PRESENT.** Unsupported RFC 7591 metadata for this public-client phase."- contacts:- type: array- nullable: true- items:- type: string- description: "**REJECTED IF PRESENT.** Unsupported RFC 7591 metadata for this public-client phase."- jwks:- type: object- nullable: true- additionalProperties: true- description: "**REJECTED IF PRESENT.** Unsupported RFC 7591 metadata for this public-client phase."- jwks_uri:- type: string- nullable: true- description: "**REJECTED IF PRESENT.** Unsupported RFC 7591 metadata for this public-client phase."-- OAuthRegisterResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] RFC 7591 §3.2.1 successful registration response."- required:- - client_id- - client_id_issued_at- - redirect_uris- - grant_types- - response_types- - token_endpoint_auth_method- - application_type- properties:- client_id:- type: string- description: Server-generated client_id.- client_id_issued_at:- type: integer- format: int64- description: Unix timestamp (seconds) when the client was registered.- client_name:- type: string- redirect_uris:- type: array- items:- type: string- grant_types:- type: array- items:- type: string- response_types:- type: array- items:- type: string- token_endpoint_auth_method:- type: string- enum: [none]- application_type:- type: string- enum: [native, web]-- OAuthRegisterError:- type: object- x-runtime: [cloud]- description: "[cloud-only] RFC 7591 §3.2.2 error response."- required:- - error- properties:- error:- type: string- enum: [invalid_redirect_uri, invalid_client_metadata]- error_description:- type: string- nullable: true-- BillingBalance:- type: object- x-runtime: [cloud]- description: "[cloud-only] Current credit balance and usage summary."- required:- - credits_remaining- properties:- credits_remaining:- type: integer- description: Available credits- credits_used:- type: integer- description: Credits used in current billing period- credits_total:- type: integer- description: Total credits allocated in current period-- BillingEvent:- type: object- x-runtime: [cloud]- description: "[cloud-only] A billing event (charge, credit, refund)."- required:- - id- - type- - amount- - created_at- properties:- id:- type: string- type:- type: string- enum: [charge, credit, refund, topup, subscription]- amount:- type: integer- description: Amount in credits- description:- type: string- job_id:- type: string- format: uuid- nullable: true- created_at:- type: string- format: date-time-- BillingEventList:- type: object- x-runtime: [cloud]- description: "[cloud-only] Paginated list of billing events."- required:- - events- - total- - has_more- properties:- events:- type: array- items:- $ref: "#/components/schemas/BillingEvent"- total:- type: integer- has_more:- type: boolean-- BillingOp:- type: object- x-runtime: [cloud]- description: "[cloud-only] A billing operation record."- required:- - id- - status- properties:- id:- type: string- status:- type: string- enum: [pending, completed, failed]- type:- type: string- amount:- type: integer- created_at:- type: string- format: date-time- completed_at:- type: string- format: date-time- nullable: true-- BillingPlan:- type: object- x-runtime: [cloud]- description: "[cloud-only] A subscription plan with pricing details."- required:- - id- - name- properties:- id:- type: string- name:- type: string- description:- type: string- credits_per_month:- type: integer- price_cents:- type: integer- description: Monthly price in cents (USD)- currency:- type: string- default: usd- features:- type: array- items:- type: string- description: List of plan features-- BillingStatus:- type: string- x-runtime: [cloud]- description: "[cloud-only] Overall billing/payment lifecycle status."- enum:- - awaiting_payment_method- - pending_payment- - paid- - payment_failed- - inactive-- BillingSubscription:- type: object- x-runtime: [cloud]- description: "[cloud-only] Active subscription details."- required:- - id- - status- - plan_id- properties:- id:- type: string- status:- type: string- enum: [active, cancelled, past_due, trialing]- plan_id:- type: string- plan_name:- type: string- current_period_start:- type: string- format: date-time- current_period_end:- type: string- format: date-time- cancel_at_period_end:- type: boolean-- SubscriptionPreview:- type: object- x-runtime: [cloud]- description: "[cloud-only] Preview of a subscription change including prorations."- properties:- plan_id:- type: string- plan_name:- type: string- amount_due:- type: integer- description: Amount due in cents- proration_amount:- type: integer- description: Proration adjustment in cents- currency:- type: string- next_billing_date:- type: string- format: date-time-- Workspace:- type: object- x-runtime: [cloud]- description: "[cloud-only] A cloud workspace for team collaboration."- required:- - id- - name- properties:- id:- type: string- name:- type: string- type:- type: string- enum:- - personal- - team- description: Workspace type (personal vs. team).- owner_id:- type: string- member_count:- type: integer- created_at:- type: string- format: date-time- updated_at:- type: string- format: date-time-- WorkspaceMember:- type: object- x-runtime: [cloud]- description: "[cloud-only] A member of a cloud workspace."- required:- - user_id- - role- properties:- user_id:- type: string- email:- type: string- format: email- display_name:- type: string- avatar_url:- type: string- format: uri- role:- type: string- enum: [owner, admin, member]- joined_at:- type: string- format: date-time-- WorkspaceInvite:- type: object- x-runtime: [cloud]- description: "[cloud-only] A pending workspace invitation."- required:- - id- - role- properties:- id:- type: string- email:- type: string- format: email- role:- type: string- enum: [admin, member]- invited_by:- type: string- created_at:- type: string- format: date-time- expires_at:- type: string- format: date-time-- WorkspaceApiKey:- type: object- x-runtime: [cloud]- description: "[cloud-only] A workspace API key (secret value redacted)."- required:- - id- - name- - description- properties:- id:- type: string- name:- type: string- description:- type: string- maxLength: 5000- description: User-provided description of the key's purpose. Always present in responses; empty string when no description was supplied on create.- prefix:- type: string- description: First few characters of the key for identification- created_at:- type: string- format: date-time- last_used_at:- type: string- format: date-time- nullable: true- created_by:- type: string-- WorkspaceApiKeyCreated:- type: object- x-runtime: [cloud]- description: "[cloud-only] A newly created workspace API key, including the full secret value (shown only once)."- required:- - id- - name- - description- - key- properties:- id:- type: string- name:- type: string- description:- type: string- maxLength: 5000- description: User-provided description of the key's purpose. Always present in responses; empty string when no description was supplied on create.- key:- type: string- description: Full API key value (only returned on creation)- prefix:- type: string- created_at:- type: string- format: date-time-- CloudUser:- type: object- x-runtime: [cloud]- description: "[cloud-only] A cloud-authenticated user profile."- required:- - id- properties:- id:- type: string- email:- type: string- format: email- display_name:- type: string- avatar_url:- type: string- format: uri- created_at:- type: string- format: date-time-- SecretMeta:- type: object- x-runtime: [cloud]- description: "[cloud-only] Metadata for a stored secret (value is never returned)."- required:- - id- - name- properties:- id:- type: string- name:- type: string- provider:- type: string- description: "[cloud-only] Provider identifier (e.g., huggingface, civitai)."- x-runtime: [cloud]- last_used_at:- type: string- format: date-time- description: "[cloud-only] When the secret was last used for decryption."- x-runtime: [cloud]- created_at:- type: string- format: date-time- updated_at:- type: string- format: date-time-- UpdateSecretRequest:- type: object- x-runtime: [cloud]- description: "[cloud-only] Request body for updating an existing user secret."- properties:- name:- type: string- description: New name for the secret- secret_value:- type: string- description: New secret value (API key, token, etc.)-- CreateSessionResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] Response after creating a session cookie."- required:- - success- properties:- success:- type: boolean- expiresIn:- type: integer- description: Session expiration time in seconds.-- DeleteSessionResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] Response after deleting a session cookie."- required:- - success- properties:- success:- type: boolean-- CreateHubProfileRequest:- type: object- x-runtime: [cloud]- description: "[cloud-only] Request body for creating a new Hub profile."- required:- - workspace_id- - username- properties:- workspace_id:- type: string- username:- type: string- description: Unique URL-safe slug. Immutable after creation.- display_name:- type: string- description:- type: string- avatar_token:- type: string- website_urls:- type: array- items:- type: string-- PublishHubWorkflowRequest:- type: object- x-runtime: [cloud]- description: "[cloud-only] Request body for publishing or updating a workflow on the Hub."- required:- - username- - name- - workflow_filename- - asset_ids- properties:- username:- type: string- name:- type: string- workflow_filename:- type: string- asset_ids:- type: array- items:- type: string- description:- type: string- tags:- type: array- items:- type: string- models:- type: array- items:- type: string- custom_nodes:- type: array- items:- type: string- tutorial_url:- type: string- metadata:- type: object- additionalProperties: true- thumbnail_type:- type: string- enum: [image, video, image_comparison]- thumbnail_token_or_url:- type: string- thumbnail_comparison_token_or_url:- type: string- sample_image_tokens_or_urls:- type: array- items:- type: string-- HubWorkflowDetail:- type: object- x-runtime: [cloud]- description: "[cloud-only] Full Hub workflow detail including versions, assets, and statistics."- required:- - share_id- - workflow_id- - name- - workflow_json- - assets- - profile- - status- properties:- share_id:- type: string- workflow_id:- type: string- name:- type: string- status:- type: string- enum: [pending, approved, rejected, deprecated]- description:- type: string- thumbnail_type:- type: string- enum: [image, video, image_comparison]- thumbnail_url:- type: string- thumbnail_comparison_url:- type: string- tutorial_url:- type: string- metadata:- type: object- additionalProperties: true- sample_image_urls:- type: array- items:- type: string- publish_time:- type: string- format: date-time- nullable: true- workflow_json:- type: object- additionalProperties: true- assets:- type: array- items:- $ref: "#/components/schemas/AssetInfo"- profile:- $ref: "#/components/schemas/HubProfile"-- AssetInfo:- type: object- x-runtime: [cloud]- description: "[cloud-only] Lightweight asset reference used in workflow publishing payloads."- required:- - id- - filename- properties:- id:- type: string- filename:- type: string- mime_type:- type: string- size_bytes:- type: integer- format: int64-- BulkRevokeAPIKeysResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] Response after bulk-revoking API keys for a workspace member."- required:- - revoked_count- properties:- revoked_count:- type: integer- minimum: 0-- CreateWorkflowVersionRequest:- type: object- x-runtime: [cloud]- description: "[cloud-only] Request body for creating a new version of a saved workflow."- required:- - base_version- - workflow_json- properties:- base_version:- type: integer- description: Version number this change is based on (for optimistic concurrency).- workflow_json:- type: object- additionalProperties: true-- WorkflowVersionResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] Metadata for a single workflow version."- required:- - id- - version- - latest_version- - created_by- - created_at- properties:- id:- type: string- version:- type: integer- latest_version:- type: integer- created_by:- type: string- created_at:- type: string- format: date-time-- WorkflowPublishInfo:- type: object- x-runtime: [cloud]- description: "[cloud-only] Publishing metadata for a workflow shared to the Hub."- required:- - workflow_id- - share_id- - listed- - assets- properties:- workflow_id:- type: string- share_id:- type: string- publish_time:- type: string- format: date-time- nullable: true- listed:- type: boolean- assets:- type: array- items:- $ref: "#/components/schemas/AssetInfo"-- TaskEntry:- type: object- x-runtime: [cloud]- description: "[cloud-only] Task data for list views."- required:- - id- - task_name- - status- - create_time- properties:- id:- type: string- format: uuid- task_name:- type: string- status:- type: string- enum: [created, running, completed, failed]- create_time:- type: string- format: date-time- started_at:- type: string- format: date-time- completed_at:- type: string- format: date-time-- TaskResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] Full task details including payload and result."- required:- - id- - idempotency_key- - task_name- - payload- - status- - create_time- - update_time- properties:- id:- type: string- format: uuid- idempotency_key:- type: string- task_name:- type: string- payload:- type: object- additionalProperties: true- status:- type: string- enum: [created, running, completed, failed]- result:- type: object- additionalProperties: true- create_time:- type: string- format: date-time- update_time:- type: string- format: date-time- started_at:- type: string- format: date-time- completed_at:- type: string- format: date-time- error:- type: string-- TasksListResponse:- type: object- x-runtime: [cloud]- description: "[cloud-only] Paginated list of background tasks for the authenticated user."- required:- - tasks- - pagination- properties:- tasks:- type: array- items:- $ref: "#/components/schemas/TaskEntry"- pagination:- $ref: "#/components/schemas/PaginationInfo"-- # ===== Cloud-only schemas (Comfy-Org/cloud runtime, BE-1106) =====- AssetDownloadResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Acknowledgement of an async asset download task; clients poll GET /api/tasks/{task_id} for status.'- required:- - task_id- - status- properties:- task_id:- type: string- format: uuid- description: Task ID for tracking download progress via GET /api/tasks/{task_id}- status:- type: string- enum:- - created- - running- - completed- - failed- description: Current task status- message:- type: string- description: Human-readable message- example: Download task created. Use task_id to track progress.-- AssetMetadataResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Metadata for a remotely hosted asset resolved by URL.'- required:- - content_length- properties:- content_length:- type: integer- format: int64- description: Size of the asset in bytes (-1 if unknown)- example: 4294967296- content_type:- type: string- description: MIME type of the asset- example: application/octet-stream- filename:- type: string- description: Suggested filename for the asset from source- example: realistic-vision-v5.safetensors- name:- type: string- description: Display name or title for the asset from source- example: Realistic Vision v5.0- tags:- type: array- items:- type: string- description: Tags for categorization from source- example:- - models- - checkpoint- preview_image:- type: string- description: Preview image as base64-encoded data URL- example: data:image/jpeg;base64,/9j/4AAQSkZJRg...- validation:- description: Validation results for the file- allOf:- - $ref: '#/components/schemas/ValidationResult'-- BillingBalanceResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Current credit balance and usage details for a workspace.'- required:- - amount_micros- - currency- properties:- amount_micros:- type: number- format: double- description: The total remaining balance in microamount (1/1,000,000 of the currency unit)- prepaid_balance_micros:- type: number- format: double- description: The remaining balance from prepaid commits in microamount- cloud_credit_balance_micros:- type: number- format: double- description: The remaining balance from cloud credits in microamount- pending_charges_micros:- type: number- format: double- description: The total amount of pending/unbilled charges from draft invoices in microamount- effective_balance_micros:- type: number- format: double- description: The effective balance (total balance minus pending charges). Can be negative if pending charges exceed- the balance.- currency:- type: string- example: usd- description: Currency code-- BillingPlansResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] List of available billing plans for subscription.'- required:- - plans- properties:- current_plan_slug:- type: string- description: Current plan slug if subscribed- plans:- type: array- items:- $ref: '#/components/schemas/Plan'-- BillingStatusResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Current billing and subscription status for a workspace.'- required:- - is_active- - has_funds- properties:- is_active:- type: boolean- description: Whether the workspace has an active subscription- subscription_status:- type: string- enum:- - active- - ended- - canceled- description: Subscription activity status (scheduled subscriptions are not returned)- subscription_tier:- $ref: '#/components/schemas/SubscriptionTier'- subscription_duration:- $ref: '#/components/schemas/SubscriptionDuration'- plan_slug:- type: string- description: Plan identifier (e.g., standard-monthly, team-pro-annual)- billing_status:- $ref: '#/components/schemas/BillingStatus'- has_funds:- type: boolean- description: Whether the workspace has available credits- cancel_at:- type: string- format: date-time- description: When the subscription will become inactive (if canceled)- renewal_date:- type: string- format: date-time- description: When the current billing period ends and the next one begins-- GetUserDataResponseFull:- type: array- x-runtime: [cloud]- description: '[cloud-only] List of user data file entries (each with path, size, and modification time) returned when full_info=true.'- items:- $ref: '#/components/schemas/GetUserDataResponseFullFile'-- HistoryDetailEntry:- type: object- x-runtime: [cloud]- description: '[cloud-only] History entry with full prompt data'- properties:- prompt:- type: object- description: Full prompt execution data- properties:- priority:- type: number- format: double- description: Execution priority- prompt_id:- type: string- description: The prompt ID- prompt:- type: object- description: The workflow nodes- additionalProperties: true- extra_data:- type: object- description: Additional execution data- additionalProperties: true- outputs_to_execute:- type: array- items:- type: string- description: Output nodes to execute- outputs:- type: object- description: Output data from execution (generated images, files, etc.)- additionalProperties: true- status:- type: object- description: Execution status and timeline information- additionalProperties: true- meta:- type: object- description: Metadata about the execution and nodes- additionalProperties: true-- HistoryDetailResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Detailed execution history response for a specific prompt.-- Returns a dictionary with prompt_id as key and full history data as value.-- '- additionalProperties:- $ref: '#/components/schemas/HistoryDetailEntry'-- HistoryResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] 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.-- '- required:- - history- properties:- history:- type: array- description: Array of history entries ordered by creation time (newest first)- items:- $ref: '#/components/schemas/HistoryEntry'-- HubLabelInfo:- type: object- x-runtime: [cloud]- description: '[cloud-only] Metadata for a single Hub label.'- required:- - name- - display_name- - type- properties:- name:- type: string- description: Slug identifier.- display_name:- type: string- description: Human-readable display name.- description:- type: string- description: Optional description of the label.- type:- type: string- enum:- - tag- - model- - custom_node- description: Label category.-- HubLabelListResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Response wrapper for the available Hub label catalog.'- required:- - labels- properties:- labels:- type: array- items:- $ref: '#/components/schemas/HubLabelInfo'- description: Available labels, optionally filtered by type.-- HubProfileSummary:- type: object- x-runtime: [cloud]- description: '[cloud-only] Abbreviated Hub profile used in workflow listings.'- required:- - username- properties:- username:- type: string- display_name:- type: string- avatar_url:- type: string- description: Public URL of the profile avatar image.-- HubWorkflowListResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Paginated list of Hub workflows matching search criteria.'- required:- - workflows- properties:- workflows:- type: array- items:- anyOf:- - $ref: '#/components/schemas/HubWorkflowSummary'- - $ref: '#/components/schemas/HubWorkflowDetail'- description: Array of HubWorkflowSummary (default) or HubWorkflowDetail (when detail=true).- next_cursor:- type: string- description: Cursor for the next page, empty if no more results.-- HubWorkflowStatus:- type: string- x-runtime: [cloud]- description: '[cloud-only] Public workflow status. NULL in the database is represented as pending in API responses.'- enum:- - pending- - approved- - rejected- - deprecated-- HubWorkflowSummary:- type: object- x-runtime: [cloud]- description: '[cloud-only] Abbreviated Hub workflow metadata used in search and listing results.'- required:- - share_id- - name- - profile- - status- properties:- share_id:- type: string- name:- type: string- status:- $ref: '#/components/schemas/HubWorkflowStatus'- description:- type: string- tags:- type: array- items:- $ref: '#/components/schemas/LabelRef'- models:- type: array- items:- $ref: '#/components/schemas/LabelRef'- custom_nodes:- type: array- items:- $ref: '#/components/schemas/LabelRef'- thumbnail_type:- type: string- enum:- - image- - video- - image_comparison- thumbnail_url:- type: string- thumbnail_comparison_url:- type: string- publish_time:- type: string- format: date-time- nullable: true- profile:- $ref: '#/components/schemas/HubProfileSummary'- metadata:- type: object- additionalProperties: true- tutorial_url:- type: string- sample_image_urls:- type: array- items:- type: string-- HubWorkflowTemplateEntry:- type: object- x-runtime: [cloud]- description: '[cloud-only] Entry in the curated workflow template gallery shown on the home page.'- required:- - name- - title- - status- properties:- name:- type: string- description: Slug identifier for the template- title:- type: string- status:- $ref: '#/components/schemas/HubWorkflowStatus'- description:- type: string- tags:- type: array- items:- type: string- models:- type: array- items:- type: string- requiresCustomNodes:- type: array- items:- type: string- thumbnailVariant:- type: string- mediaType:- type: string- mediaSubtype:- type: string- size:- type: integer- format: int64- description: Workflow asset size in bytes.- vram:- type: integer- format: int64- description: Approximate VRAM requirement in bytes.- usage:- type: integer- format: int64- description: Usage count reported upstream.- searchRank:- type: integer- format: int64- description: Search ranking score reported upstream.- isEssential:- type: boolean- description: Whether the template belongs to a module marked as essential.- openSource:- type: boolean- profile:- $ref: '#/components/schemas/HubProfileSummary'- tutorialUrl:- type: string- logos:- type: array- items:+ history:+ description: Array of history entries ordered by creation time (newest first)+ items:+ $ref: '#/components/schemas/HistoryEntry'+ type: array+ required:+ - history+ type: object+ JobCancelResponse:+ description: Response for POST /api/jobs/{job_id}/cancel. Returned on both fresh cancels and idempotent no-ops.+ properties:+ cancelled:+ description: |+ True when a cancel event was successfully dispatched by this call.+ False when the job was already in a terminal or cancelling state,+ in which case the call is a no-op (still 200 — idempotent).+ type: boolean+ required:+ - cancelled+ type: object+ JobDetailResponse:+ description: Full job details including workflow and outputs+ properties:+ create_time:+ description: Job creation timestamp (Unix timestamp in milliseconds)+ format: int64+ type: integer+ execution_error:+ allOf:+ - $ref: '#/components/schemas/ExecutionError'+ description: Detailed execution error from ComfyUI (only for failed jobs with structured error data)+ execution_meta:+ additionalProperties: true+ description: Node-level execution metadata (only for terminal states)+ type: object+ execution_status:+ additionalProperties: true+ description: ComfyUI execution status and timeline (only for terminal states)+ type: object+ id:+ description: Unique job identifier+ format: uuid+ type: string+ outputs:+ additionalProperties: true+ description: Full outputs object from ComfyUI (only for terminal states)+ type: object+ outputs_count:+ description: Total number of output files (omitted for non-terminal states)+ type: integer+ preview_output:+ additionalProperties: true+ description: Primary preview output (only for terminal states)+ type: object+ status:+ description: User-friendly job status+ enum:+ - pending+ - in_progress+ - completed+ - failed+ - cancelled+ type: string+ update_time:+ description: Last update timestamp (Unix timestamp in milliseconds)+ format: int64+ type: integer+ workflow:+ additionalProperties: true+ description: |+ Full ComfyUI workflow (10-100KB, omitted if not available).++ Sensitive credentials are redacted before the response is returned:+ `extra_data.api_key_comfy_org`, when present, is replaced with the+ literal string `"[REDACTED]"`. The field is preserved (not removed)+ so existence checks still pass, but the value is not usable.+ type: object+ workflow_id:+ description: UUID identifying the workflow graph definition+ type: string+ required:+ - id+ - status+ - create_time+ - update_time+ type: object+ JobEntry:+ description: Lightweight job data for list views (workflow and full outputs excluded)+ properties:+ create_time:+ description: Job creation timestamp (Unix timestamp in milliseconds)+ format: int64+ type: integer+ execution_end_time:+ description: Workflow execution completion timestamp (Unix milliseconds, only present for terminal states)+ format: int64+ type: integer+ execution_error:+ allOf:+ - $ref: '#/components/schemas/ExecutionError'+ description: Detailed execution error from ComfyUI (only for failed jobs with structured error data)+ execution_start_time:+ description: Workflow execution start timestamp (Unix milliseconds, only present for terminal states)+ format: int64+ type: integer+ id:+ description: Unique job identifier+ format: uuid+ type: string+ outputs_count:+ description: Total number of output files (omitted for non-terminal states)+ type: integer+ preview_output:+ additionalProperties: true+ description: Primary preview output (only present for terminal states)+ type: object+ status:+ description: User-friendly job status+ enum:+ - pending+ - in_progress+ - completed+ - failed+ - cancelled+ type: string+ workflow_id:+ description: UUID identifying the workflow graph definition+ type: string+ required:+ - id+ - status+ - create_time+ type: object+ JobStatusResponse:+ description: Job status information+ properties:+ assigned_inference:+ description: The inference instance assigned to this job (if any)+ nullable: true+ type: string+ created_at:+ description: When the job was created+ format: date-time+ type: string+ error_message:+ description: Error message if the job failed+ nullable: true+ type: string+ id:+ description: The job ID+ format: uuid+ type: string+ last_state_update:+ description: When the job status was last changed+ format: date-time+ type: string+ status:+ description: Current job status+ enum:+ - waiting_to_dispatch+ - pending+ - in_progress+ - completed+ - error+ - cancelled+ type: string+ updated_at:+ description: When the job was last updated+ format: date-time+ type: string+ required:+ - id+ - status+ - created_at+ - updated_at+ type: object+ JobsListResponse:+ description: Paginated list of jobs for the authenticated user.+ properties:+ jobs:+ description: Array of jobs ordered by specified sort field+ items:+ $ref: '#/components/schemas/JobEntry'+ type: array+ pagination:+ $ref: '#/components/schemas/PaginationInfo'+ required:+ - jobs+ - pagination+ type: object+ ListAssetsResponse:+ description: Paginated list of assets belonging to the authenticated user.+ properties:+ assets:+ description: List of assets matching the query+ items:+ $ref: '#/components/schemas/Asset'+ type: array+ has_more:+ description: Whether more assets are available beyond this page+ type: boolean+ next_cursor:+ description: |+ Opaque cursor to pass as the `after` query parameter to fetch the+ next page. Omitted from the response when there are no more results.+ type: string+ total:+ description: Total number of assets matching the filters+ type: integer+ required:+ - assets+ - total+ - has_more+ type: object+ ListTagsResponse:+ description: Paginated list of available asset tags.+ properties:+ has_more:+ description: Whether more tags are available+ type: boolean+ tags:+ description: List of tags+ items:+ $ref: '#/components/schemas/TagInfo'+ type: array+ total:+ description: Total number of tags+ type: integer+ required:+ - tags+ - total+ - has_more+ type: object+ ModelFile:+ description: Represents a model file with metadata+ properties:+ name:+ description: The filename of the model+ example: model.safetensors+ type: string+ pathIndex:+ description: Index of the path where this model is located+ example: 0+ type: integer+ required:+ - name+ - pathIndex+ type: object+ ModelFolder:+ description: Represents a folder containing models+ properties:+ folders:+ description: List of paths where models of this type are stored+ example:+ - checkpoints+ items:+ type: string+ type: array+ name:+ description: The name of the model folder+ example: checkpoints+ type: string+ required:+ - name+ - folders+ type: object+ NodeInfo:+ description: Metadata describing a single ComfyUI node type and its inputs/outputs.+ properties:+ api_node:+ description: Whether this is an API node+ type: boolean+ category:+ description: Category of the node+ type: string+ deprecated:+ description: Whether the node is deprecated+ type: boolean+ description:+ description: Description of the node+ type: string+ display_name:+ description: Display name of the node+ type: string+ experimental:+ description: Whether the node is experimental+ type: boolean+ input:+ additionalProperties: true+ description: Input specifications for the node+ type: object+ input_order:+ additionalProperties:+ items:+ type: string+ type: array+ description: Order of inputs for display+ type: object+ name:+ description: Internal name of the node+ type: string+ output:+ description: Output types of the node+ items:+ type: string+ type: array+ output_is_list:+ description: Whether each output is a list+ items:+ type: boolean+ type: array+ output_name:+ description: Names of the outputs+ items:+ type: string+ type: array+ output_node:+ description: Whether this is an output node+ type: boolean+ output_tooltips:+ description: Tooltips for outputs+ items:+ type: string+ type: array+ python_module:+ description: Python module implementing the node+ type: stringtype: object+ PaginationInfo:+ description: Offset/limit-based pagination metadata included in list responses.+ properties:+ has_more:+ description: Whether more items are available beyond this page+ type: boolean+ limit:+ description: Items per page+ minimum: 1+ type: integer+ offset:+ description: Current offset (0-based)+ minimum: 0+ type: integer+ total:+ description: Total number of items matching filters+ minimum: 0+ type: integer+ required:+ - offset+ - limit+ - total+ - has_more+ type: object+ PromptErrorResponse:additionalProperties: true- date:- type: string- description: Publication date in YYYY-MM-DD format- io:- type: object- properties:- inputs:- type: array- items:- type: object- additionalProperties: true- outputs:- type: array- items:- type: object- additionalProperties: true- includeOnDistributions:- type: array- items:- type: string- thumbnailUrl:- type: string- description: Public URL of the primary thumbnail- thumbnailComparisonUrl:- type: string- description: Public URL of the comparison thumbnail- shareId:- type: string- description: Share ID for linking to the hub workflow detail- extendedDescription:- type: string- description: AI-generated extended description of the workflow- metaDescription:- type: string- description: AI-generated SEO meta description (under 160 chars)- howToUse:- type: array- items:- type: string- description: AI-generated step-by-step usage instructions- suggestedUseCases:- type: array- items:- type: string- description: AI-generated suggested use cases- faqItems:- type: array- items:+ description: Error response for ComfyUI prompt execution.+ type: object+ PromptInfo:+ description: Metadata about the currently running and queued prompts.+ properties:+ exec_info:+ properties:+ queue_remaining:+ description: Number of items remaining in the queue+ type: integer+ type: object+ type: object+ PromptRequest:+ description: Request body for submitting a ComfyUI workflow prompt for execution.+ properties:+ extra_data:+ additionalProperties: true+ description: Extra data to be associated with the prompt+ type: object+ front:+ description: If true, adds the prompt to the front of the queue+ type: boolean+ number:+ description: Priority number for the queue (lower numbers have higher priority)+ type: number+ partial_execution_targets:+ description: List of node names to execute+ items:+ type: string+ type: array+ prompt:+ additionalProperties: true+ description: The workflow graph to execute+ type: object+ workflow_id:+ description: UUID identifying the cloud workflow entity to associate with this job+ type: string+ workflow_version_id:+ description: UUID identifying the workflow version to associate with this job+ type: string+ required:+ - prompt+ type: object+ PromptResponse:+ description: Response returned after successfully queuing a workflow prompt.+ properties:+ node_errors:+ additionalProperties: true+ description: Any errors in the nodes of the prompt+ type: object+ number:+ description: Priority number in the queue+ type: number+ prompt_id:+ description: Unique identifier for the prompt execution+ format: uuid+ type: string+ type: object+ PublishWorkflowAssetsRequest:+ description: Request body for publishing workflow assets to the Hub.+ properties:+ asset_ids:+ description: IDs of assets (inputs and models) to snapshot.+ items:+ type: string+ type: array+ required:+ - asset_ids+ type: object+ PublishedWorkflowDetail:+ description: Full detail of a publicly published workflow on the Hub.+ properties:+ assets:+ description: Published assets with their library status for the caller.+ items:+ $ref: '#/components/schemas/AssetInfo'+ type: array+ listed:+ type: boolean+ name:+ description: Human-readable workflow name.+ type: string+ publish_time:+ format: date-time+ nullable: true+ type: string+ share_id:+ type: string+ workflow_id:+ type: string+ workflow_json:+ additionalProperties: true+ description: The workflow JSON content at publish time.+ type: object+ required:+ - share_id+ - workflow_id+ - name+ - listed+ - workflow_json+ - assets+ type: object+ QueueInfo:+ description: Queue information with pending and running jobs+ properties:+ queue_pending:+ description: Array of pending job items (ordered by creation time, oldest first)+ items:+ description: |+ Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata]+ - [0] job_number (integer): Position in queue (1-based)+ - [1] prompt_id (string): Job UUID+ - [2] workflow_json (object): Full ComfyUI workflow+ - [3] output_node_ids (array): Node IDs to return results from+ - [4] metadata (object): Contains {create_time: <milliseconds>}+ items: {}+ maxItems: 5+ minItems: 5+ type: array+ type: array+ queue_running:+ description: Array of currently running job items+ items:+ description: |+ Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata]+ - [0] job_number (integer): Position in queue (1-based)+ - [1] prompt_id (string): Job UUID+ - [2] workflow_json (object): Full ComfyUI workflow+ - [3] output_node_ids (array): Node IDs to return results from+ - [4] metadata (object): Contains {create_time: <milliseconds>}+ items: {}+ maxItems: 5+ minItems: 5+ type: array+ type: array+ type: object+ QueueManageRequest:+ additionalProperties: false+ description: Request to manage queue operations+ properties:+ clear:+ description: If true, clear all pending jobs from the queue+ type: boolean+ delete:+ description: Array of PENDING job IDs to cancel+ items:+ type: string+ type: array+ type: object+ QueueManageResponse:+ description: Response after a queue management action (delete or clear).+ properties:+ cleared:+ description: Whether the queue was cleared+ type: boolean+ deleted:+ description: Array of job IDs that were successfully cancelled+ items:+ type: string+ type: array+ type: object+ SystemStatsResponse:+ description: System statistics response+ properties:+ devices:+ items:+ properties:+ name:+ description: Device name+ type: string+ type:+ description: Device type+ type: string+ vram_free:+ description: Free VRAM in bytes+ type: number+ vram_total:+ description: Total VRAM in bytes+ type: number+ required:+ - name+ - type+ type: object+ type: array+ system:+ properties:+ argv:+ description: Command line arguments+ items:+ type: string+ type: array+ cloud_version:+ description: Cloud ingest service version (commit hash)+ type: string+ comfyui_frontend_version:+ description: ComfyUI frontend version (commit hash or tag)+ type: string+ comfyui_version:+ description: ComfyUI version+ type: string+ embedded_python:+ description: Whether using embedded Python+ type: boolean+ os:+ description: Operating system+ type: string+ python_version:+ description: Python version+ type: string+ pytorch_version:+ description: PyTorch version+ type: string+ ram_free:+ description: Free RAM in bytes+ type: number+ ram_total:+ description: Total RAM in bytes+ type: number+ workflow_templates_version:+ description: Workflow templates version+ type: string+ required:+ - os+ - python_version+ - embedded_python+ - comfyui_version+ - pytorch_version+ - argv+ - ram_total+ - ram_free+ type: object+ required:+ - system+ - devices+ type: object+ TagInfo:+ description: Metadata for a single tag that can be applied to assets.+ properties:+ count:+ description: Number of assets using this tag+ type: integer+ name:+ description: Tag name+ type: string+ required:+ - name+ - count+ type: object+ TagsModificationResponse:+ description: Response after adding, updating, or removing tags on an asset.+ properties:+ added:+ description: Tags that were successfully added (for add operation)+ items:+ type: string+ type: array+ already_present:+ description: Tags that were already present (for add operation)+ items:+ type: string+ type: array+ not_present:+ description: Tags that were not present (for remove operation)+ items:+ type: string+ type: array+ removed:+ description: Tags that were successfully removed (for remove operation)+ items:+ type: string+ type: array+ total_tags:+ description: All tags on the asset after the operation+ items:+ type: string+ type: array+ required:+ - total_tags+ type: object+ TaskEntry:+ description: Task data for list views+ properties:+ completed_at:+ description: When task completed or failed (null if not finished)+ format: date-time+ type: string+ create_time:+ description: Task creation timestamp+ format: date-time+ type: string+ id:+ description: Unique task identifier+ format: uuid+ type: string+ started_at:+ description: When task execution started (null if not started)+ format: date-time+ type: string+ status:+ description: Current task status+ enum:+ - created+ - running+ - completed+ - failed+ type: string+ task_name:+ description: Task type name (e.g., model_upload)+ type: string+ required:+ - id+ - task_name+ - status+ - create_time+ type: object+ TaskResponse:+ description: Full task details including payload and result+ properties:+ completed_at:+ description: When task completed or failed (null if not finished)+ format: date-time+ type: string+ create_time:+ description: Task creation timestamp+ format: date-time+ type: string+ error_message:+ description: Error message on failure (null if not failed)+ type: string+ id:+ description: Unique task identifier+ format: uuid+ type: string+ idempotency_key:+ description: Caller-provided key for idempotent task creation+ type: string+ payload:+ additionalProperties: true+ description: Task input data+ type: object+ result:+ additionalProperties: true+ description: Task output data (null if not completed)+ type: object+ started_at:+ description: When task execution started (null if not started)+ format: date-time+ type: string+ status:+ description: Current task status+ enum:+ - created+ - running+ - completed+ - failed+ type: string+ task_name:+ description: Task type name (e.g., model_upload)+ type: string+ update_time:+ description: Task last update timestamp+ format: date-time+ type: string+ required:+ - id+ - idempotency_key+ - task_name+ - payload+ - status+ - create_time+ - update_time+ type: object+ TasksListResponse:+ description: Paginated list of background tasks for the authenticated user.+ properties:+ pagination:+ $ref: '#/components/schemas/PaginationInfo'+ tasks:+ description: Array of tasks ordered by create_time+ items:+ $ref: '#/components/schemas/TaskEntry'+ type: array+ required:+ - tasks+ - pagination+ type: object+ UpdateWorkflowRequest:+ description: Request body for updating an existing saved workflow.+ properties:+ default_view:+ description: New default view mode+ enum:+ - workflow+ - app+ type: string+ description:+ description: New description+ type: string+ name:+ description: New display name+ type: string+ type: object+ UserDataResponseFull:+ description: User data listing entry with file metadata (path, size, modification time).+ properties:+ modified:+ description: UNIX timestamp of the last modification in milliseconds.+ format: int64+ type: integer+ path:+ type: string+ size:+ type: integer+ type: object+ UserResponse:+ description: User information response+ properties:+ id:+ description: Firebase UID of the authenticated user+ type: string+ status:+ description: User status (always "active" for authenticated users)+ type: string+ required:+ - id+ - status+ type: object+ WorkflowForkedFrom:+ description: Reference to the parent workflow from which this workflow was forked.+ properties:+ workflow_id:+ type: string+ workflow_version_id:+ type: string+ type: object+ WorkflowListResponse:+ description: Paginated list of saved workflows.+ properties:+ data:+ items:+ $ref: '#/components/schemas/WorkflowResponse'+ type: array+ pagination:+ $ref: '#/components/schemas/PaginationInfo'+ required:+ - data+ - pagination+ type: object+ WorkflowPublishInfo:+ description: Publishing metadata for a workflow shared to the Hub.+ properties:+ assets:+ description: Published assets (inputs and models).+ items:+ $ref: '#/components/schemas/AssetInfo'+ type: array+ listed:+ type: boolean+ publish_time:+ format: date-time+ nullable: true+ type: string+ share_id:+ type: string+ workflow_id:+ type: string+ required:+ - workflow_id+ - share_id+ - listed+ - assets+ type: object+ WorkflowResponse:+ description: Full workflow entity including metadata and version history.+ properties:+ created_at:+ format: date-time+ type: string+ created_by:+ type: string+ default_view:+ enum:+ - workflow+ - app+ type: string+ description:+ type: string+ forked_from:+ $ref: '#/components/schemas/WorkflowForkedFrom'+ id:+ type: string+ latest_version:+ type: integer+ name:+ type: string+ updated_at:+ format: date-time+ type: string+ required:+ - id+ - latest_version+ - created_by+ - created_at+ - updated_attype: 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: integerrequired:- - question- - answer- properties:- question:- type: string- answer:- type: string- description: AI-generated FAQ items- contentTemplate:- type: string- description: Content template used for generation (tutorial, showcase, comparison, breakthrough)-- JobStatusResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Job status information'- properties:- id:- type: string- format: uuid- description: The job ID- status:- type: string- enum:- - waiting_to_dispatch- - pending- - in_progress- - completed- - error- - cancelled- description: Current job status- created_at:- type: string- format: date-time- description: When the job was created- updated_at:- type: string- format: date-time- description: When the job was last updated- last_state_update:- type: string- format: date-time- description: When the job status was last changed- assigned_inference:- type: string- nullable: true- description: The inference instance assigned to this job (if any)- error_message:- type: string- nullable: true- description: Error message if the job failed- required:- - id- - status- - created_at- - updated_at-- JobsListResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Paginated list of jobs for the authenticated user.'- required:- - jobs- - pagination- properties:- jobs:- type: array- description: Array of jobs ordered by specified sort field- items:- $ref: '#/components/schemas/JobEntry'- pagination:- $ref: '#/components/schemas/PaginationInfo'-- LabelRef:- type: object- x-runtime: [cloud]- description: '[cloud-only] Reference to a Hub label by ID.'- required:- - name- - display_name- properties:- name:- type: string- description: Slug identifier (e.g. "video-generation", "flux").- display_name:- type: string- description: Human-readable display name (e.g. "Video Generation", "Flux").-- LogsResponse:- type: array- x-runtime: [cloud]- description: '[cloud-only] System logs response'- items:- type: object- properties:- timestamp:- type: string- format: date-time- description: When the log entry was created- level:- type: string- enum:- - debug- - info- - warn- - error- description: Log level- message:- type: string- description: Log message- source:- type: string- description: Source of the log entry- metadata:+ - id+ - version+ - latest_version+ - created_by+ - created_attype: object- additionalProperties: true- description: Additional log metadata-- Member:- type: object- x-runtime: [cloud]- description: '[cloud-only] Workspace member with profile and role information.'- required:- - id- - name- - role- - joined_at- properties:- id:- type: string- description: User ID- name:- type: string- description: User's display name- email:- type: string- format: email- description: User's email address- role:- type: string- enum:- - owner- - member- description: User's role in the workspace- joined_at:- type: string- format: date-time- description: When the user joined the workspace-- OAuthRegisterBadRequestResponse:- x-runtime: [cloud]- description: "[cloud-only] Union of the two 400 shapes /oauth/register can emit. `OAuthRegisterError` is the handler-shaped\- \ RFC 7591 \xA73.2.2 error; `BindingErrorResponse` is the strict-server binding-layer error fired when the request body\- \ fails OpenAPI-schema validation before the handler runs.\n"- oneOf:- - $ref: '#/components/schemas/OAuthRegisterError'- - $ref: '#/components/schemas/BindingErrorResponse'-- PendingInvite:- type: object- x-runtime: [cloud]- description: '[cloud-only] An outstanding workspace invitation that has not yet been accepted.'- required:- - id- - invited_at- - expires_at- properties:- id:- type: string- description: Invite ID- email:- type: string- format: email- description: Email address of the invited user- token:- type: string- description: Invite token for constructing invite links. Empty for expired invites.- invited_at:- type: string- format: date-time- description: When the invite was created- expires_at:- type: string- format: date-time- description: When the invite expires-- Plan:- type: object- x-runtime: [cloud]- description: '[cloud-only] Billing plan details including pricing, limits, and features.'- required:- - slug- - tier- - duration- - price_cents- - credits_cents- - max_seats- - availability- - seat_summary- properties:- slug:- type: string- description: Plan identifier (e.g., "pro-monthly", "team-standard-annual")- example: pro-monthly- tier:- $ref: '#/components/schemas/SubscriptionTier'- duration:- $ref: '#/components/schemas/SubscriptionDuration'- price_cents:- type: integer- format: int64- description: Per-member price in cents (base + one seat)- example: 10000- credits_cents:- type: integer- format: int64- description: Per-member credits in cents (base + one seat)- example: 10000- max_seats:- type: integer- format: int64- description: Maximum number of seats allowed for this plan- example: 20- availability:- $ref: '#/components/schemas/PlanAvailability'- seat_summary:- $ref: '#/components/schemas/PlanSeatSummary'-- PlanAvailability:- type: object- x-runtime: [cloud]- description: '[cloud-only] Availability and eligibility information for a billing plan.'- required:- - available- properties:- available:- type: boolean- description: Whether the workspace can subscribe to this plan- reason:- $ref: '#/components/schemas/PlanAvailabilityReason'-- PlanAvailabilityReason:- type: string- x-runtime: [cloud]- enum:- - same_plan- - incompatible_transition- - requires_team- - requires_personal- - exceeds_max_seats- description: '[cloud-only] Reason why a plan is unavailable'-- PlanSeatSummary:- type: object- x-runtime: [cloud]- description: '[cloud-only] Summary of seat costs based on current workspace members'- required:- - seat_count- - total_cost_cents- - total_credits_cents- properties:- seat_count:- type: integer- description: Total number of seats (owner + members) that would be charged- example: 5- total_cost_cents:- type: integer- format: int64- description: Total cost for all seats in cents- example: 50000- total_credits_cents:- type: integer- format: int64- description: Total credits granted for all seats in cents- example: 50000-- PreviewPlanInfo:- type: object- x-runtime: [cloud]- description: '[cloud-only] Plan information for preview display'- required:- - slug- - tier- - duration- - price_cents- - credits_cents- - seat_summary- properties:- slug:- type: string- description: Plan slug- example: team-pro-monthly- tier:- $ref: '#/components/schemas/SubscriptionTier'- duration:- $ref: '#/components/schemas/SubscriptionDuration'- price_cents:- type: integer- format: int64- description: Per-seat price in cents- example: 10000- credits_cents:- type: integer- format: int64- description: Per-seat credits in cents- example: 10000- seat_summary:- $ref: '#/components/schemas/PlanSeatSummary'- period_start:- type: string- format: date-time- description: Current billing period start (only for current_plan)- period_end:- type: string- format: date-time- description: Current billing period end (only for current_plan)-- PreviewSubscribeResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Itemized cost preview for a pending subscription change.'- required:- - allowed- - transition_type- - effective_at- - is_immediate- - cost_today_cents- - cost_next_period_cents- - credits_today_cents- - credits_next_period_cents- - new_plan- properties:- allowed:- type: boolean- description: Whether this subscription change is allowed- reason:- type: string- description: Reason why the change is not allowed (only present if allowed=false)- transition_type:- type: string- enum:- - new_subscription- - upgrade- - downgrade- - duration_change- description: Type of subscription transition- effective_at:- type: string- format: date-time- description: When the change takes effect- is_immediate:- type: boolean- description: Whether the change takes effect immediately (true) or at period end (false)- cost_today_cents:- type: integer- format: int64- description: Amount to charge today in cents (0 for downgrades)- example: 5000- cost_next_period_cents:- type: integer- format: int64- description: Amount that will be charged at next billing period in cents- example: 10000- credits_today_cents:- type: integer- format: int64- description: Credits granted today in cents (prorated for mid-period upgrades)- example: 5000- credits_next_period_cents:- type: integer- format: int64- description: Credits that will be granted at next billing period in cents- example: 10000- current_plan:- $ref: '#/components/schemas/PreviewPlanInfo'- new_plan:- $ref: '#/components/schemas/PreviewPlanInfo'-- PublishedWorkflowDetail:- type: object- x-runtime: [cloud]- description: '[cloud-only] Full detail of a publicly published workflow on the Hub.'- required:- - share_id- - workflow_id- - name- - listed- - workflow_json- - assets- properties:- share_id:- type: string- workflow_id:- type: string- name:- type: string- description: Human-readable workflow name.- listed:- type: boolean- publish_time:- type: string- format: date-time- nullable: true- workflow_json:- type: object- additionalProperties: true- description: The workflow JSON content at publish time.- assets:- type: array- description: Published assets with their library status for the caller.- items:- $ref: '#/components/schemas/AssetInfo'-- SecretResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] User secret metadata (the secret value itself is never returned after creation).'- required:- - id- - name- - created_at- - updated_at- properties:- id:- type: string- format: uuid- description: Unique identifier for the secret- name:- type: string- description: User-provided label for the secret- provider:- type: string- description: Provider identifier (e.g., huggingface, civitai)- last_used_at:- type: string- format: date-time- description: When the secret was last used for decryption- created_at:- type: string- format: date-time- description: When the secret was created- updated_at:- type: string- format: date-time- description: When the secret was last updated-- SubscriptionDuration:- type: string- x-runtime: [cloud]- enum:- - MONTHLY- - ANNUAL- description: '[cloud-only] Billing period (uppercase to match comfy-api)'-- SubscriptionTier:- type: string- x-runtime: [cloud]- enum:- - FREE- - STANDARD- - CREATOR- - PRO- - FOUNDERS_EDITION- description: '[cloud-only] Subscription tier (uppercase to match comfy-api)'-- UserDataResponseFull:- type: object- x-runtime: [cloud]- description: '[cloud-only] User data listing entry with file metadata (path, size, modification time).'- properties:- path:- type: string- size:- type: integer- modified:- type: integer- format: int64- description: UNIX timestamp of the last modification in milliseconds.-- ValidationError:- type: object- x-runtime: [cloud]- description: '[cloud-only] Details of a single validation error encountered during asset operations.'- required:- - code- - message- - field- properties:- code:- type: string- description: Machine-readable error code- example: FORMAT_NOT_ALLOWED- message:- type: string- description: Human-readable error message- example: 'File format "PickleTensor" is not allowed. Allowed formats: [SafeTensor]'- field:- type: string- description: Field that failed validation- example: format-- ValidationResult:- type: object- x-runtime: [cloud]- description: '[cloud-only] Result of validating a set of asset operations.'- required:- - is_valid- properties:- is_valid:- type: boolean- description: Overall validation status (true if all checks passed)- example: true- errors:- type: array- items:- $ref: '#/components/schemas/ValidationError'- description: Blocking validation errors that prevent download- warnings:- type: array- items:- $ref: '#/components/schemas/ValidationError'- description: Non-blocking validation warnings (informational only)-- WorkflowForkedFrom:- type: object- x-runtime: [cloud]- description: '[cloud-only] Reference to the parent workflow from which this workflow was forked.'- properties:- workflow_id:- type: string- workflow_version_id:- type: string-- WorkflowResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Full workflow entity including metadata and version history.'- required:- - id- - latest_version- - created_by- - created_at- - updated_at- properties:- id:- type: string- name:- type: string- description:- type: string- default_view:- type: string- enum:- - workflow- - app- latest_version:- type: integer- forked_from:- $ref: '#/components/schemas/WorkflowForkedFrom'- created_by:- type: string- created_at:- type: string- format: date-time- updated_at:- type: string- format: date-time-- WorkflowVersionContentResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Full workflow version including the serialized workflow JSON.'- required:- - id- - version- - workflow_json- - created_by- - created_at- properties:- id:- type: string- version:- type: integer- workflow_json:- type: object- additionalProperties: true- created_by:- type: string- created_at:- type: string- format: date-time- dependency_asset_ids:- type: array- items:- type: string-- WorkspaceAPIKeyInfo:- type: object- x-runtime: [cloud]- description: '[cloud-only] Metadata for a workspace-scoped API key (secret is never returned).'- required:- - id- - workspace_id- - user_id- - name- - description- - key_prefix- - created_at- properties:- id:- type: string- format: uuid- description: API key ID- workspace_id:- type: string- description: Workspace this key belongs to- user_id:- type: string- description: User who created this key- name:- type: string- description: User-provided label- description:- type: string- description: User-provided description of the key's purpose. Limit is byte-based (UTF-8 encoding); 5000 bytes equals- 5000 ASCII characters or fewer multi-byte characters.- maxLength: 5000- key_prefix:- type: string- description: First 8 chars after prefix for display- expires_at:- type: string- format: date-time- description: When the key expires (if set)- last_used_at:- type: string- format: date-time- description: Last time the key was used- revoked_at:- type: string- format: date-time- description: When the key was revoked (if revoked)- created_at:- type: string- format: date-time- description: When the key was created-- WorkspaceSummary:- type: object- x-runtime: [cloud]- description: '[cloud-only] Abbreviated workspace metadata used in list responses.'- required:- - id- - name- - type- properties:- id:- type: string- example: w-a1b2c3d4-5678-90ab-cdef-1234567890ab- name:- type: string- example: My Team- type:- type: string- enum:- - personal- - team-- WorkspaceWithRole:- type: object- x-runtime: [cloud]- description: '[cloud-only] Workspace entity annotated with the requesting user''s role.'- required:- - id- - name- - type- - role- - created_at- - joined_at- properties:- id:- type: string- example: w-a1b2c3d4-5678-90ab-cdef-1234567890ab- name:- type: string- example: My Team- type:- type: string- enum:- - personal- - team- role:- type: string- enum:- - owner- - member- created_at:- type: string- format: date-time- description: When the workspace was created- joined_at:- type: string- format: date-time- description: When the user joined the workspace (same as created_at for the workspace creator)- subscription_tier:- $ref: '#/components/schemas/SubscriptionTier'-- BindingErrorResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Error shape returned when request binding or validation fails before the handler runs.'- required:- - message- properties:- message:- type: string-- ErrorResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Standard error response from cloud endpoints with a machine-readable code and human-readable message.'- required:- - code- - message- properties:- code:- type: string- description: Machine-readable error code- message:- type: string- description: Human-readable error message-- AcceptInviteResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Response returned after successfully accepting a workspace invitation.'- required:- - workspace_id- - workspace_name- properties:- workspace_id:- type: string- description: ID of the workspace joined- workspace_name:- type: string- description: Name of the workspace joined-- BillingEventsResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Paginated list of billing events for a workspace.'- required:- - total- - events- - page- - limit- - totalPages- properties:- total:- type: integer- description: Total number of events- events:- type: array- items:- $ref: '#/components/schemas/BillingEvent'- page:- type: integer- description: Current page number (1-indexed)- limit:- type: integer- description: Items per page- totalPages:- type: integer- description: Total number of pages-- BillingOpStatusResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Status of an asynchronous billing operation.'- required:- - id- - status- - started_at- properties:- id:- type: string- description: Unique identifier for the billing operation- status:- type: string- enum:- - pending- - succeeded- - failed- description: Current status of the operation- error_message:- type: string- description: Error message if status is failed- started_at:- type: string- format: date-time- description: When the operation was initiated- completed_at:- type: string- format: date-time- description: When the operation completed (success or failure)-- CancelSubscriptionResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Response after successfully cancelling a subscription.'- required:- - cancel_at- - billing_op_id- properties:- billing_op_id:- type: string- description: Billing operation ID to poll for status via GET /api/billing/ops/{id}- cancel_at:- type: string- format: date-time- description: The date when the subscription will end (end of current billing period)-- CreateTopupResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Response after successfully purchasing a credit top-up.'- required:- - topup_id- - status- - amount_cents- - billing_op_id- properties:- billing_op_id:- type: string- description: Billing operation ID to poll for status via GET /api/billing/ops/{id}- topup_id:- type: string- description: Unique identifier for the top-up request (same as billing_op_id, deprecated)- status:- type: string- enum:- - pending- - completed- - failed- description: Current status of the top-up- amount_cents:- type: integer- format: int64- description: Amount being charged in cents-- CreateWorkspaceAPIKeyResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Response containing the newly created workspace API key.'- required:- - id- - name- - description- - key- - key_prefix- - created_at- properties:- id:- type: string- format: uuid- description: API key ID- name:- type: string- description: User-provided label- description:- type: string- description: User-provided description of the key's purpose. Limit is byte-based (UTF-8 encoding); 5000 bytes equals- 5000 ASCII characters or fewer multi-byte characters.- maxLength: 5000- key:- type: string- description: The full plaintext API key (only shown once)- key_prefix:- type: string- description: First 8 chars after prefix for display- expires_at:- type: string- format: date-time- description: When the key expires (if set)- created_at:- type: string- format: date-time- description: When the key was created-- ExchangeTokenResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Response containing the issued Cloud JWT and its expiry.'- required:- - token- - expires_at- - workspace- - role- - permissions- properties:- token:- type: string- description: Cloud JWT token- expires_at:- type: string- format: date-time- description: Token expiration time (RFC 3339)- workspace:- $ref: '#/components/schemas/WorkspaceSummary'- role:- type: string- enum:- - owner- - member- description: User's role in the workspace- permissions:- type: array- items:- type: string- description: Permission strings for the role- example:- - owner:*-- JobCancelResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Response for POST /api/jobs/{job_id}/cancel. Returned on both fresh cancels and idempotent no-ops.'- required:- - cancelled- properties:- cancelled:- type: boolean- description: "True when a cancel event was successfully dispatched by this call.\nFalse when the job was already in\- \ a terminal or cancelling state,\nin which case the call is a no-op (still 200 \u2014 idempotent).\n"-- ResubscribeResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Response after successfully resubscribing to a billing plan.'- required:- - status- - billing_op_id- properties:- billing_op_id:- type: string- description: Billing operation ID to poll for status via GET /api/billing/ops/{id}- status:- type: string- enum:- - active- description: The subscription status after resubscribing- message:- type: string- description: Human-readable confirmation message-- SubscribeResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Response after successfully subscribing to a billing plan.'- required:- - status- - billing_op_id- properties:- billing_op_id:- type: string- description: Billing operation ID to poll for status via GET /api/billing/ops/{id}- status:- type: string- enum:- - subscribed- - needs_payment_method- - pending_payment- description: 'Status of the subscription operation:-- - subscribed: Subscription is active immediately-- - needs_payment_method: User must add payment method via payment_method_url-- - pending_payment: Upgrade initiated, waiting for payment to complete+ 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. Preferred over asset_hash.+ in: query+ name: hash+ schema:+ type: string+ - deprecated: true+ description: 'Deprecated: use hash instead. Filter assets by exact content hash.'+ in: query+ name: asset_hash+ schema:+ type: string+ - description: |+ Opaque cursor for keyset pagination. Pass the `next_cursor` value+ from the previous response to fetch the next page. When provided,+ `offset` is ignored. Cursor pagination is only supported with+ `sort` values `created_at`, `updated_at`, `name`, or `size`;+ requests combining `after` with other sort fields return 400.+ The cursor must have been minted under the same `sort` value used+ in the follow-up request.+ in: query+ name: after+ schema:+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ListAssetsResponse'+ description: Success - Assets returned+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request parameters+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: List user assets+ tags:+ - file+ post:+ description: |+ Uploads a new asset to the system with associated metadata.+ Supports two upload methods:+ 1. Direct file upload (multipart/form-data)+ 2. URL-based upload (application/json with source: "url")++ If an asset with the same hash already exists, returns the existing asset.+ operationId: uploadAsset+ requestBody:+ content:+ application/json:+ schema:+ properties:+ name:+ description: Display name for the asset (used to determine file extension)+ type: string+ preview_id:+ description: Optional preview asset ID+ format: uuid+ type: string+ tags:+ description: Freeform tags for the asset. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.+ items:+ type: string+ type: array+ url:+ description: HTTP/HTTPS URL to download the asset from+ format: uri+ type: string+ user_metadata:+ additionalProperties: true+ description: Custom metadata to store with the asset+ type: object+ required:+ - url+ - name+ type: object+ multipart/form-data:+ schema:+ properties:+ file:+ description: The asset file to upload+ format: binary+ type: string+ id:+ description: Optional asset ID for idempotent creation. If provided and asset exists, returns existing asset.+ format: uuid+ type: string+ mime_type:+ description: MIME type of the asset (e.g., "image/png", "video/mp4")+ type: string+ name:+ description: Display name for the asset+ type: string+ preview_id:+ description: Optional preview asset ID. If not provided, images will use their own ID as preview.+ format: uuid+ type: string+ tags:+ description: Freeform tags for the asset. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.+ items:+ type: string+ type: array+ user_metadata:+ description: Custom JSON metadata as a string+ type: string+ required:+ - file+ type: object+ required: true+ responses:+ "201":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/AssetCreated'+ description: Asset created successfully+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request (bad file, invalid URL, invalid content type, etc.)+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "403":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Source URL requires authentication or access denied+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Source URL not found+ "413":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: File too large+ "415":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unsupported media type+ "422":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Download failed due to network error or timeout+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Upload a new asset+ tags:+ - file+ /api/assets/{id}:+ delete:+ description: Deletes 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., workflow version)+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Delete asset+ tags:+ - file+ get:+ description: Retrieves detailed information about a specific asset+ operationId: getAssetById+ parameters:+ - description: Asset ID+ in: path+ name: id+ required: true+ schema:+ format: uuid+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/Asset'+ description: Asset details retrieved successfully+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Asset not found+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Get asset details+ tags:+ - file+ put:+ description: |+ Updates an asset's metadata. At least one field must be provided.+ Only name, mime_type, preview_id, and user_metadata can be updated.+ For tag management, use the dedicated PUT /api/assets/{id}/tags endpoint.+ operationId: updateAsset+ parameters:+ - description: Asset ID+ in: path+ name: id+ required: true+ schema:+ format: uuid+ type: string+ requestBody:+ content:+ application/json:+ schema:+ minProperties: 1+ properties:+ mime_type:+ description: Updated MIME type of the asset+ type: string+ name:+ description: New display name for the asset+ type: string+ preview_id:+ description: Updated preview asset ID+ format: uuid+ type: string+ user_metadata:+ additionalProperties: true+ description: Updated custom metadata+ type: object+ type: object+ required: true+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/AssetUpdated'+ description: Asset updated successfully+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request (no fields provided)+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Asset not found+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Update asset metadata+ tags:+ - file+ /api/assets/{id}/tags:+ delete:+ description: Removes one or more tags from an existing asset+ operationId: removeAssetTags+ parameters:+ - description: Asset ID+ in: path+ name: id+ required: true+ schema:+ format: uuid+ type: string+ requestBody:+ content:+ application/json:+ schema:+ properties:+ tags:+ description: Tags to remove from the asset+ items:+ type: string+ minItems: 1+ type: array+ required:+ - tags+ type: object+ required: true+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/TagsModificationResponse'+ description: Tags removed successfully+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Asset not found+ "422":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Validation error (e.g., reserved tag)+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Remove tags from asset+ tags:+ - file+ post:+ description: Adds one or more tags to an existing asset+ operationId: addAssetTags+ parameters:+ - description: Asset ID+ in: path+ name: id+ required: true+ schema:+ format: uuid+ type: string+ requestBody:+ content:+ application/json:+ schema:+ properties:+ tags:+ description: Tags to add to the asset+ items:+ type: string+ minItems: 1+ type: array+ required:+ - tags+ type: object+ required: true+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/TagsModificationResponse'+ description: Tags added successfully+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Asset not found+ "422":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Validation error (e.g., reserved tag)+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Add tags to asset+ tags:+ - file+ put:+ description: Adds and removes tags from an asset in a single operation+ operationId: updateAssetTags+ parameters:+ - description: Asset ID+ in: path+ name: id+ required: true+ schema:+ format: uuid+ type: string+ requestBody:+ content:+ application/json:+ schema:+ description: At least one of add or remove must contain items. Empty arrays are allowed when the other array has items.+ minProperties: 1+ properties:+ add:+ description: Tags to add to the asset. Can be empty if remove has items.+ items:+ type: string+ type: array+ remove:+ description: Tags to remove from the asset. Can be empty if add has items.+ items:+ type: string+ type: array+ type: object+ required: true+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/TagsModificationResponse'+ description: Tags updated successfully+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Asset not found+ "422":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Reserved tag validation error+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Update asset tags+ tags:+ - file+ /api/assets/from-hash:+ post:+ description: |+ Creates a new asset reference using an existing asset's hash.+ This avoids re-uploading the file content when the asset already exists in storage.+ The user can provide their own metadata and tags for the reference.+ operationId: createAssetFromHash+ requestBody:+ content:+ application/json:+ schema:+ properties:+ hash:+ description: Hash of the existing asset. Supports Blake3 (blake3:) or SHA256 (sha256:) formats+ pattern: ^(blake3|sha256):[a-f0-9]{64}$+ type: string+ mime_type:+ description: MIME type of the asset (e.g., "image/png", "video/mp4")+ type: string+ name:+ description: Display name for the asset reference (optional)+ type: string+ tags:+ description: Freeform tags for the asset. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.+ items:+ type: string+ minItems: 1+ type: array+ user_metadata:+ additionalProperties: true+ description: Custom metadata for this asset reference+ type: object+ required:+ - hash+ - tags+ type: object+ required: true+ responses:+ "201":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/AssetCreated'+ description: Asset reference created successfully+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request (bad hash format, invalid tags, etc.)+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Source asset with given hash not found+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Create asset reference from existing hash+ tags:+ - file+ /api/assets/hash/{hash}:+ head:+ description: |+ Checks if an asset exists in the system by its blake3 hash.+ Returns 200 if the asset exists, 404 if it doesn't.+ operationId: checkAssetByHash+ parameters:+ - description: Blake3 hash of the asset in format 'blake3:hex_digest'+ in: path+ name: hash+ required: true+ schema:+ example: blake3:a1b2c3d4e5f67890123456789012345678901234567890123456789012345678+ pattern: ^blake3:[a-f0-9]{64}$+ type: string+ responses:+ "200":+ description: Asset exists+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid hash format+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "404":+ description: Asset not found+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Check if asset exists by hash+ tags:+ - file+ /api/assets/prune:+ post:+ description: Starts a background job that removes asset entries whose underlying content no longer exists on disk.+ operationId: pruneAssets+ responses:+ "200":+ content:+ application/json:+ schema:+ properties:+ marked:+ description: Number of assets marked as missing+ type: integer+ status:+ type: string+ type: object+ description: Prune result+ summary: Mark assets whose backing files no longer exist on disk+ /api/assets/seed:+ post:+ description: Starts a background job that scans configured directories and registers assets not yet in the asset database.+ operationId: seedAssets+ requestBody:+ content:+ application/json:+ schema:+ properties:+ roots:+ description: Root folder paths to scan (if omitted, scans all)+ items:+ type: string+ type: array+ type: object+ responses:+ "200":+ content:+ application/json:+ schema:+ properties:+ status:+ type: string+ type: object+ description: Seed started+ summary: Trigger asset scan/seed from filesystem+ /api/assets/seed/cancel:+ post:+ description: Requests cancellation of the currently-running asset seed job.+ operationId: cancelAssetSeed+ responses:+ "200":+ content:+ application/json:+ schema:+ properties:+ status:+ type: string+ type: object+ description: Scan cancelled+ summary: Cancel an in-progress asset scan+ /api/assets/seed/status:+ get:+ description: Returns progress/status of the most recent asset seed job.+ operationId: getAssetSeedStatus+ responses:+ "200":+ content:+ application/json:+ schema:+ additionalProperties: true+ description: Scan progress details (files scanned, total, status, etc.)+ type: object+ description: Scan progress+ summary: Get asset scan progress+ /api/assets/tags/refine:+ get:+ description: |+ Returns a histogram of tags appearing on assets matching the given filters.+ Useful for refining asset searches by showing available tags and their counts.+ Only returns tags with non-zero counts (tags that exist on matching assets).+ operationId: getAssetTagHistogram+ parameters:+ - description: Filter assets that have ALL of these tags+ explode: false+ in: query+ name: include_tags+ schema:+ items:+ type: string+ type: array+ style: form+ - description: Exclude assets that have ANY of these tags+ explode: false+ in: query+ name: exclude_tags+ schema:+ items:+ type: string+ type: array+ style: form+ - description: Filter assets where name contains this substring (case-insensitive)+ in: query+ name: name_contains+ schema:+ type: string+ - description: JSON object for filtering by metadata fields+ in: query+ name: metadata_filter+ schema:+ type: string+ - description: Maximum number of tags to return (1-1000, default 100)+ in: query+ name: limit+ schema:+ default: 100+ maximum: 1000+ minimum: 1+ type: integer+ - description: Whether to include public/shared assets in results+ in: query+ name: include_public+ schema:+ default: true+ type: boolean+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/AssetTagHistogramResponse'+ description: Success - Tag histogram returned+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request parameters+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Get tag histogram for filtered assets+ tags:+ - file+ /api/embeddings:+ get:+ description: Returns the list of text-encoder embeddings available on disk.+ operationId: getEmbeddings+ responses:+ "200":+ content:+ application/json:+ schema:+ items:+ type: string+ type: array+ description: Embedding names+ summary: List available embedding names+ /api/experiment/models:+ get:+ description: |+ Returns a list of model folders available in the system.+ This is an experimental endpoint that replaces the legacy /models endpoint.+ operationId: getModelFolders+ responses:+ "200":+ content:+ application/json:+ schema:+ items:+ $ref: '#/components/schemas/ModelFolder'+ type: array+ description: Success - List of model folders+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ security: []+ summary: Get available model folders+ tags:+ - file+ /api/experiment/models/{folder}:+ get:+ description: |+ Returns a list of models available in the specified folder.+ This is an experimental endpoint that provides enhanced model information.+ operationId: getModelsInFolder+ parameters:+ - description: The folder name to list models from+ in: path+ name: folder+ required: true+ schema:+ example: checkpoints+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ items:+ $ref: '#/components/schemas/ModelFile'+ type: array+ description: Success - List of models in the folder+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Folder not found or no models in folder+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ security: []+ summary: Get models in a specific folder+ tags:+ - file+ /api/extensions:+ get:+ description: |+ Returns the list of custom node web extension JS files available for+ loading by the ComfyUI frontend. Paths are relative to the web root+ (e.g. `/extensions/VHS.core.js`).+ operationId: getExtensions+ responses:+ "200":+ content:+ application/json:+ schema:+ description: URL paths (relative to web root) of available extension JS files+ items:+ type: string+ type: array+ description: JSON array of extension file paths+ security: []+ summary: List custom node JS extensions+ tags:+ - node+ /api/features:+ get:+ description: Returns the server's feature capabilities+ operationId: getFeatures+ responses:+ "200":+ content:+ application/json:+ schema:+ additionalProperties: true+ properties:+ max_upload_size:+ description: Maximum upload size in bytes+ type: integer+ supports_preview_metadata:+ description: Whether the server supports preview metadata+ type: boolean+ type: object+ description: Success+ headers:+ Cache-Control:+ description: Short-lived private cache to deduplicate rapid-fire calls from the frontend+ schema:+ type: string+ Vary:+ description: Cache key includes auth headers so anonymous and authenticated responses are stored separately+ schema:+ type: string+ security:+ - ApiKeyAuth: []+ - BearerAuth: []+ - CookieAuth: []+ - {}+ summary: Get server feature flags+ tags:+ - node+ /api/feedback:+ post:+ description: Submit feedback about the ComfyUI service+ operationId: submitFeedback+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/FeedbackRequest'+ required: true+ responses:+ "201":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/FeedbackResponse'+ description: Feedback submitted successfully+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Submit user feedback+ tags:+ - feedback+ /api/files/mask-layers:+ get:+ description: |+ Given a mask file (any of the 4 layers), returns all related mask layer files.+ This is used by the mask editor to load the paint, mask, and painted layers+ when reopening a previously edited mask.+ operationId: getMaskLayers+ parameters:+ - description: Hash filename of any mask layer file+ in: query+ name: filename+ required: true+ schema:+ example: abc123def456.png+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ properties:+ mask:+ description: Filename of the mask layer+ nullable: true+ type: string+ paint:+ description: Filename of the paint strokes layer+ nullable: true+ type: string+ painted:+ description: Filename of the painted image layer+ nullable: true+ type: string+ painted_masked:+ description: Filename of the final composite layer+ nullable: true+ type: string+ type: object+ description: Success - Related mask layers returned+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: File not found or not a mask file+ summary: Get related mask layer files+ tags:+ - file+ /api/free:+ post:+ description: Frees GPU memory by unloading models and/or freeing the resident model cache.+ operationId: freeMemory+ requestBody:+ content:+ application/json:+ schema:+ properties:+ free_memory:+ description: Run garbage collection and free cached memory+ type: boolean+ unload_models:+ description: Unload all models from VRAM/RAM+ type: boolean+ type: object+ responses:+ "200":+ description: Memory freed+ summary: Free GPU memory and/or unload models+ /api/global_subgraphs:+ get:+ description: |+ Returns a list of globally available subgraph blueprints.+ These are pre-built workflow components that can be used as nodes.+ The data field contains a promise that resolves to the full subgraph JSON.+ operationId: getGlobalSubgraphs+ responses:+ "200":+ content:+ application/json:+ schema:+ additionalProperties:+ $ref: '#/components/schemas/GlobalSubgraphInfo'+ type: object+ description: Success - Map of subgraph IDs to their metadata+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ security: []+ summary: Get available subgraph blueprints+ tags:+ - workflow+ /api/global_subgraphs/{id}:+ get:+ description: Returns the full data for a specific subgraph blueprint by ID+ operationId: getGlobalSubgraph+ parameters:+ - description: The unique identifier of the subgraph blueprint+ in: path+ name: id+ required: true+ schema:+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/GlobalSubgraphData'+ description: Success - Full subgraph data+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Subgraph not found+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ security: []+ summary: Get a specific subgraph blueprint+ tags:+ - workflow+ /api/history:+ post:+ deprecated: true+ description: |+ **Deprecated.** Superseded by the job-management endpoints under+ `/api/jobs`. Planned for removal no earlier than a future major+ release; sunset timeline TBD.++ Clear all history for the authenticated user or delete specific job IDs.+ Supports clearing all history or deleting specific job IDs.+ operationId: manageHistory+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/HistoryManageRequest'+ required: true+ responses:+ "200":+ description: Success - History management operation completed+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request parameters+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized - Authentication required+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Manage execution history+ tags:+ - workflow+ /api/history_v2:+ get:+ deprecated: true+ description: |+ **Deprecated.** Superseded by `GET /api/jobs`, which returns the same+ execution records in a paginated, filterable format. Planned for removal+ no earlier than a future major release; sunset timeline TBD.++ Retrieve execution history for the authenticated user with pagination support.+ Returns a lightweight history format with filtered prompt data (workflow removed from extra_pnginfo).+ operationId: getHistory+ parameters:+ - description: Maximum number of items to return+ in: query+ name: max_items+ schema:+ type: integer+ - description: Starting position (default 0)+ in: query+ name: offset+ schema:+ default: 0+ type: integer+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/HistoryResponse'+ description: Success - Execution history retrieved+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized - Authentication required+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Get execution history (v2)+ tags:+ - workflow+ /api/history_v2/{prompt_id}:+ get:+ deprecated: true+ description: |+ **Deprecated.** Superseded by `GET /api/jobs/{job_id}`, which returns+ the same execution record. Planned for removal no earlier than a future+ major release; sunset timeline TBD.++ Retrieve detailed execution history for a specific prompt ID.+ Returns full history data including complete prompt information.+ operationId: getHistoryForPrompt+ parameters:+ - description: The prompt ID to retrieve history for+ in: path+ name: prompt_id+ required: true+ schema:+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/HistoryDetailResponse'+ description: Success - History for prompt retrieved+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized - Authentication required+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Prompt not found+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Get history for specific prompt+ tags:+ - workflow+ /api/i18n:+ get:+ description: Returns translation file URLs contributed by custom nodes, keyed by locale.+ operationId: getI18n+ responses:+ "200":+ content:+ application/json:+ schema:+ additionalProperties: true+ description: Nested map of locale to translation key-value pairs+ type: object+ description: Translation map+ summary: Get internationalisation translation strings+ /api/interrupt:+ post:+ description: |+ Cancel all currently RUNNING jobs for the authenticated user.+ This will interrupt any job that is currently in 'in_progress' status.+ Note: This endpoint only affects running jobs. To cancel pending jobs, use /api/queue.+ operationId: interruptJob+ responses:+ "200":+ description: Success - Job interrupted or no running job found+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized - Authentication required+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Interrupt currently running jobs+ tags:+ - queue+ /api/job/{job_id}/status:+ get:+ deprecated: true+ description: |+ **Deprecated.** Superseded by `GET /api/jobs/{job_id}` (plural path).+ Clients should migrate; the endpoint is retained for backward+ compatibility but will be removed in a future release.+ operationId: getJobStatus+ parameters:+ - description: The unique ID of the job+ in: path+ name: job_id+ required: true+ schema:+ format: uuid+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/JobStatusResponse'+ description: Success - Job status returned+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "403":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Forbidden - job belongs to another user+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Job not found+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Get job status (deprecated)+ tags:+ - job+ /api/jobs:+ get:+ description: |+ Retrieve a paginated list of jobs for the authenticated user.+ Returns lightweight job data optimized for list views.+ Workflow and full outputs are excluded to reduce payload size.+ operationId: listJobs+ parameters:+ - description: Filter by one or more statuses (comma-separated). If not provided, returns all jobs.+ example: pending,in_progress+ in: query+ name: status+ schema:+ type: string+ - description: Filter by workflow ID (exact match)+ example: 550e8400-e29b-41d4-a716-446655440000+ in: query+ name: workflow_id+ schema:+ type: string+ - description: Filter by output media type (only applies to completed jobs with outputs)+ example: image+ in: query+ name: output_type+ schema:+ enum:+ - image+ - video+ - audio+ - 3d+ type: string+ - description: Field to sort by (create_time = when job was submitted, execution_time = how long workflow took to run)+ example: execution_time+ in: query+ name: sort_by+ schema:+ default: create_time+ enum:+ - create_time+ - execution_time+ type: string+ - description: Sort direction (asc = ascending, desc = descending)+ in: query+ name: sort_order+ schema:+ default: desc+ enum:+ - asc+ - desc+ type: string+ - description: Pagination offset (0-based)+ in: query+ name: offset+ schema:+ default: 0+ minimum: 0+ type: integer+ - description: Maximum items per page (1-1000)+ in: query+ name: limit+ schema:+ default: 100+ maximum: 1000+ minimum: 1+ type: integer+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/JobsListResponse'+ description: Success - Jobs retrieved+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized - Authentication required+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: List jobs with pagination and filtering+ tags:+ - workflow+ /api/jobs/{job_id}:+ get:+ description: |+ Retrieve complete details for a specific job including workflow and outputs.+ Used for detail views, workflow re-execution, and debugging.+ operationId: getJobDetail+ parameters:+ - description: Job identifier (UUID)+ in: path+ name: job_id+ required: true+ schema:+ format: uuid+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/JobDetailResponse'+ description: Success - Job details retrieved+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized - Authentication required+ "403":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Forbidden - Job does not belong to user+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Job not found+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Get full job details+ tags:+ - workflow+ /api/jobs/{job_id}/cancel:+ post:+ description: |+ Cancel a specific job for the authenticated user.++ Idempotent: a job that is already in a terminal state (completed, failed,+ cancelled) or already cancelling is treated as a successful no-op and+ returns 200. Only truly missing or cross-user jobs return 404.+ operationId: cancelJob+ parameters:+ - description: Job identifier (UUID)+ in: path+ name: job_id+ required: true+ schema:+ format: uuid+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/JobCancelResponse'+ description: Success - Cancel request accepted (or job was already terminal)+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/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/node_replacements:+ get:+ description: |+ Returns mappings of unsupported node class names to their cloud-installed replacements.+ Used by the frontend to offer "Quick Fix" when a workflow contains missing nodes.+ operationId: getNodeReplacements+ responses:+ "200":+ content:+ application/json:+ schema:+ additionalProperties: true+ type: object+ description: Success - Node replacement mappings+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ security: []+ summary: Get node replacement mappings+ tags:+ - node+ /api/object_info:+ get:+ description: Returns information about all available nodes+ operationId: getNodeInfo+ responses:+ "200":+ content:+ application/json:+ schema:+ additionalProperties:+ $ref: '#/components/schemas/NodeInfo'+ type: object+ description: Success+ summary: Get all node information+ tags:+ - node+ /api/prompt:+ get:+ description: Returns information about the current prompt in the execution queue+ operationId: getPromptInfo+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/PromptInfo'+ description: Success+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Get information about current prompt execution+ tags:+ - workflow+ post:+ description: |+ Submit a workflow to be executed by the backend.+ The workflow is a JSON object describing the nodes and their connections.+ operationId: executePrompt+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/PromptRequest'+ required: true+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/PromptResponse'+ description: Success - Prompt accepted+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/PromptErrorResponse'+ description: Invalid prompt+ "402":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/PromptErrorResponse'+ description: Payment required - Insufficient credits+ "429":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/PromptErrorResponse'+ description: Payment required - User has not paid+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/PromptErrorResponse'+ description: Internal server error+ "503":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/PromptErrorResponse'+ description: Service unavailable+ summary: Submit a workflow for execution+ tags:+ - workflow+ /api/queue:+ get:+ description: Returns information about running and pending items in the queue+ operationId: getQueueInfo+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/QueueInfo'+ description: Success+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request parameters+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request parameters+ summary: Get queue information+ tags:+ - queue+ post:+ description: |+ Cancel specific PENDING jobs by ID or clear all pending jobs in the queue.+ Note: This endpoint only affects pending jobs. To cancel running jobs, use /api/interrupt.+ operationId: manageQueue+ requestBody:+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/QueueManageRequest'+ required: true+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/QueueManageResponse'+ description: Success+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request parameters+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Manage queue operations+ tags:+ - queue+ /api/settings:+ get:+ description: Returns all settings for the authenticated user+ operationId: getAllSettings+ responses:+ "200":+ content:+ application/json:+ schema:+ additionalProperties: true+ description: User settings as key-value pairs+ type: object+ description: Success+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ summary: Get all user settings+ tags:+ - settings+ post:+ description: Update multiple settings (merge with existing)+ operationId: updateMultipleSettings+ requestBody:+ content:+ application/json:+ schema:+ additionalProperties: true+ description: Settings to update as key-value pairs+ type: object+ text/plain:+ schema:+ description: JSON string of settings to update+ type: string+ required: true+ responses:+ "200":+ content:+ application/json:+ schema:+ additionalProperties: true+ description: Updated user settings+ type: object+ description: Success+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ summary: Update multiple settings+ tags:+ - settings+ /api/settings/{id}:+ get:+ description: Returns a specific setting value by its id+ operationId: getSettingById+ parameters:+ - description: Setting id to retrieve+ in: path+ name: id+ required: true+ schema:+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ description: Setting value response+ properties:+ value:+ description: The setting value+ type: object+ description: Success+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Setting not found+ summary: Get a specific setting by id+ tags:+ - settings+ post:+ description: Update a specific setting by its id+ operationId: updateSettingById+ parameters:+ - description: Setting id to update+ in: path+ name: id+ required: true+ schema:+ type: string+ requestBody:+ content:+ application/json:+ schema:+ description: New value for the setting+ text/plain:+ schema:+ description: JSON string of the new setting value+ type: string+ required: true+ responses:+ "200":+ content:+ application/json:+ schema:+ description: Updated setting value response+ properties:+ value:+ description: The updated setting value+ type: object+ description: Success+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ summary: Update a specific setting by id+ tags:+ - settings+ /api/system_stats:+ get:+ description: Returns system statistics including ComfyUI version, device info, and system resources+ operationId: getSystemStats+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/SystemStatsResponse'+ description: Success+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ security: []+ summary: Get system statistics+ tags:+ - system+ /api/tags:+ get:+ description: |+ Retrieves a list of all tags used across assets.+ Includes usage counts and filtering options.+ operationId: listTags+ parameters:+ - description: Filter tags by prefix+ in: query+ name: prefix+ schema:+ type: string+ - description: Maximum number of tags to return (1-1000)+ in: query+ name: limit+ schema:+ default: 100+ maximum: 1000+ minimum: 1+ type: integer+ - description: Number of tags to skip for pagination+ in: query+ name: offset+ schema:+ default: 0+ minimum: 0+ type: integer+ - description: Sort order for tags+ in: query+ name: order+ schema:+ default: count_desc+ enum:+ - count_desc+ - name_asc+ type: string+ - description: Include tags with zero usage count+ in: query+ name: include_zero+ schema:+ default: false+ type: boolean+ - description: Whether to include public/shared assets when counting tags+ in: query+ name: include_public+ schema:+ default: true+ type: boolean+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ListTagsResponse'+ description: Tags retrieved successfully+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Invalid request parameters+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: List all tags+ tags:+ - file+ /api/tasks:+ get:+ description: |+ Retrieve a paginated list of background tasks for the authenticated user.+ Supports filtering by task type, status, and creation time.+ operationId: listTasks+ parameters:+ - description: Filter by task type name (exact match)+ example: model_upload+ in: query+ name: task_name+ schema:+ type: string+ - description: Filter by idempotency key (exact match). For best performance, specify task_name as well.+ example: upload-model-abc123+ in: query+ name: idempotency_key+ schema:+ type: string+ - description: Filter by one or more statuses (comma-separated)+ example: created,running+ in: query+ name: status+ schema:+ type: string+ - description: Filter tasks created after this timestamp (RFC3339 format)+ example: "2024-01-01T00:00:00Z"+ in: query+ name: created_after+ schema:+ format: date-time+ type: string+ - description: Filter tasks created before this timestamp (RFC3339 format)+ example: "2024-12-31T23:59:59Z"+ in: query+ name: created_before+ schema:+ format: date-time+ type: string+ - description: Sort direction (asc = ascending, desc = descending by create_time)+ in: query+ name: sort_order+ schema:+ default: desc+ enum:+ - asc+ - desc+ type: string+ - description: Pagination offset (0-based)+ in: query+ name: offset+ schema:+ default: 0+ minimum: 0+ type: integer+ - description: Maximum items per page (1-100)+ in: query+ name: limit+ schema:+ default: 20+ maximum: 100+ minimum: 1+ type: integer+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/TasksListResponse'+ description: Success - Tasks retrieved+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized - Authentication required+ "422":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Validation error - Invalid filter values+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: List background tasks+ tags:+ - task+ /api/tasks/{task_id}:+ get:+ description: |+ Retrieve full details for a specific background task.+ operationId: getTask+ parameters:+ - description: Task identifier (UUID)+ in: path+ name: task_id+ required: true+ schema:+ format: uuid+ type: string+ responses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/TaskResponse'+ description: Success - Task details retrieved+ "401":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Unauthorized - Authentication required+ "404":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Task not found (also returned for ownership failures to avoid leaking task existence)+ "500":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Internal server error+ summary: Get task details+ tags:+ - task+ /api/upload/image:+ post:+ description: |+ Upload an image file to cloud storage.- '- effective_at:- type: string- format: date-time- description: When the subscription became/becomes active (present when status=subscribed or pending_payment)- payment_method_url:- type: string- description: URL to redirect user to add payment method (present when status=needs_payment_method)+ Image limits:+ - Maximum file size: 50 MB+ - Maximum width/height per edge: 16384 px+ - Maximum total pixel count: 64 megapixels (67108864 pixels)- UserResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] User information response'- required:- - id- - status- properties:- id:- type: string- description: Firebase UID of the authenticated user- status:- type: string- description: User status (always "active" for authenticated users)+ 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.- WorkflowListResponse:- type: object- x-runtime: [cloud]- description: '[cloud-only] Paginated list of saved workflows.'- required:- - data- - pagination- properties:- data:- type: array- items:- $ref: '#/components/schemas/WorkflowResponse'- pagination:- $ref: '#/components/schemas/PaginationInfo'+ 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)- FeedbackRequest:- type: object- x-runtime: [cloud]- description: "[cloud-only] User feedback submission body."- required:- - message- properties:- type:- type: string- enum:- - missing_nodes- - general- - missing_models- description: Feedback category- category:- type: string- description: Additional category metadata- message:- type: string- description: User-provided feedback message+ 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