mirror of
https://github.com/comfyanonymous/ComfyUI.git
synced 2026-05-10 01:02:56 +08:00
9bd5710acb
- PUT /api/assets/{id}/preview: sets the preview asset for an existing asset,
returns the full updated Asset object. Returns 404 if asset ID doesn't exist.
- DELETE /api/assets/{id}/preview: clears the preview asset link, returns 204.
Returns 404 if asset ID doesn't exist.
Added OpenAPI spec entries under the assets tag with no x-runtime restriction.
Implemented handlers using the existing set_asset_preview service function.
Added integration tests covering happy paths and 404 cases.
Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com>
8136 lines
238 KiB
YAML
8136 lines
238 KiB
YAML
openapi: 3.1.0
|
|
info:
|
|
title: ComfyUI API
|
|
description: |
|
|
API for ComfyUI - A powerful and modular stable diffusion GUI and backend.
|
|
|
|
This API allows you to interact with ComfyUI programmatically, including:
|
|
- Submitting and managing workflow executions
|
|
- Querying node/object information
|
|
- Uploading and viewing files
|
|
- Managing user settings and data
|
|
- Asset management (feature-gated)
|
|
|
|
## Dual-path routing
|
|
Every route registered via `self.routes` in the ComfyUI server is available at
|
|
both its bare path (e.g. `/prompt`) and an `/api`-prefixed path (e.g. `/api/prompt`).
|
|
This spec uses the `/api`-prefixed versions as canonical.
|
|
|
|
## Multi-user mode
|
|
When ComfyUI is started with `--multi-user`, the `Comfy-User` header identifies
|
|
the active user for settings, userdata, and history isolation. This is **not** a
|
|
security mechanism — it is an organisational convenience with no authentication
|
|
or authorisation behind it.
|
|
version: 1.0.0
|
|
license:
|
|
name: GNU General Public License v3.0
|
|
url: https://github.com/comfyanonymous/ComfyUI/blob/master/LICENSE
|
|
|
|
servers:
|
|
- url: /
|
|
description: Default ComfyUI server (typically http://127.0.0.1:8188)
|
|
|
|
tags:
|
|
- name: prompt
|
|
description: Workflow submission and prompt info
|
|
- name: queue
|
|
description: Queue inspection and management
|
|
- name: history
|
|
description: Execution history
|
|
- name: upload
|
|
description: File upload endpoints
|
|
- name: view
|
|
description: File viewing / download
|
|
- name: system
|
|
description: System stats and feature flags
|
|
- name: node
|
|
description: Node / object_info definitions
|
|
- name: model
|
|
description: Model folder and file listing
|
|
- name: user
|
|
description: User management (multi-user mode)
|
|
- name: userdata
|
|
description: Per-user file storage
|
|
- name: settings
|
|
description: Per-user settings
|
|
- name: extensions
|
|
description: Frontend extension JS files
|
|
- name: subgraph
|
|
description: Global subgraph blueprints
|
|
- name: internal
|
|
description: Internal / debug endpoints
|
|
- name: assets
|
|
description: Asset management (feature-gated behind enable-assets)
|
|
|
|
- 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)
|
|
|
|
paths:
|
|
# ---------------------------------------------------------------------------
|
|
# WebSocket
|
|
# ---------------------------------------------------------------------------
|
|
/ws:
|
|
get:
|
|
operationId: connectWebSocket
|
|
tags: [system]
|
|
summary: WebSocket connection for real-time updates
|
|
description: |
|
|
Upgrades to a WebSocket connection that streams execution progress,
|
|
node status, and output messages. The server sends an initial `status`
|
|
message with the session ID (SID) on connect.
|
|
|
|
## Message types (server → client)
|
|
The server sends JSON messages with a `type` field. See the
|
|
`x-websocket-messages` list below for the schema of each message type.
|
|
parameters:
|
|
- name: clientId
|
|
in: query
|
|
required: false
|
|
schema:
|
|
type: string
|
|
description: Client identifier. If omitted the server assigns one.
|
|
responses:
|
|
"101":
|
|
description: WebSocket upgrade successful
|
|
x-websocket-messages:
|
|
- type: status
|
|
schema:
|
|
$ref: "#/components/schemas/StatusWsMessage"
|
|
- type: progress
|
|
schema:
|
|
$ref: "#/components/schemas/ProgressWsMessage"
|
|
- type: progress_text
|
|
schema:
|
|
$ref: "#/components/schemas/ProgressTextWsMessage"
|
|
- type: progress_state
|
|
schema:
|
|
$ref: "#/components/schemas/ProgressStateWsMessage"
|
|
- type: executing
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutingWsMessage"
|
|
- type: executed
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutedWsMessage"
|
|
- type: execution_start
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutionStartWsMessage"
|
|
- type: execution_success
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutionSuccessWsMessage"
|
|
- type: execution_cached
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutionCachedWsMessage"
|
|
- type: execution_interrupted
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutionInterruptedWsMessage"
|
|
- type: execution_error
|
|
schema:
|
|
$ref: "#/components/schemas/ExecutionErrorWsMessage"
|
|
- type: logs
|
|
schema:
|
|
$ref: "#/components/schemas/LogsWsMessage"
|
|
- type: notification
|
|
schema:
|
|
$ref: "#/components/schemas/NotificationWsMessage"
|
|
- type: feature_flags
|
|
schema:
|
|
$ref: "#/components/schemas/FeatureFlagsWsMessage"
|
|
- type: asset_download
|
|
schema:
|
|
$ref: "#/components/schemas/AssetDownloadWsMessage"
|
|
- type: asset_export
|
|
schema:
|
|
$ref: "#/components/schemas/AssetExportWsMessage"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Prompt
|
|
# ---------------------------------------------------------------------------
|
|
/api/prompt:
|
|
get:
|
|
operationId: getPromptInfo
|
|
tags: [prompt]
|
|
summary: Get queue status
|
|
description: Returns how many items remain in the execution queue.
|
|
responses:
|
|
"200":
|
|
description: Queue info
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/PromptInfo"
|
|
post:
|
|
operationId: executePrompt
|
|
tags: [prompt]
|
|
summary: Submit a workflow for execution
|
|
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"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Queue
|
|
# ---------------------------------------------------------------------------
|
|
/api/queue:
|
|
get:
|
|
operationId: getQueue
|
|
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"
|
|
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
|
|
|
|
/api/interrupt:
|
|
post:
|
|
operationId: interruptExecution
|
|
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
|
|
|
|
/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"
|
|
|
|
/api/jobs/{job_id}:
|
|
get:
|
|
operationId: getJob
|
|
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
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# History
|
|
# ---------------------------------------------------------------------------
|
|
/api/history:
|
|
get:
|
|
operationId: getHistory
|
|
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"
|
|
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
|
|
|
|
/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"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# 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
|
|
|
|
/api/upload/mask:
|
|
post:
|
|
operationId: uploadMask
|
|
tags: [upload]
|
|
summary: Upload a mask image
|
|
description: 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
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# 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
|
|
|
|
/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"
|
|
|
|
/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:
|
|
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:
|
|
type: string
|
|
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: getObjectInfo
|
|
tags: [node]
|
|
summary: Get all node definitions
|
|
description: |
|
|
Returns a dictionary of every registered node class, keyed by class name.
|
|
Each value is a NodeInfo object describing inputs, outputs, category, etc.
|
|
responses:
|
|
"200":
|
|
description: All node definitions
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties:
|
|
$ref: "#/components/schemas/NodeInfo"
|
|
|
|
/api/object_info/{node_class}:
|
|
get:
|
|
operationId: getObjectInfoByClass
|
|
tags: [node]
|
|
summary: Get a single node definition
|
|
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
|
|
|
|
/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: getExperimentModels
|
|
tags: [model]
|
|
summary: List model folders with paths
|
|
description: Returns an array of model folder objects with name and folder paths.
|
|
responses:
|
|
"200":
|
|
description: Model folders
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/ModelFolder"
|
|
|
|
/api/experiment/models/{folder}:
|
|
get:
|
|
operationId: getExperimentModelsByFolder
|
|
tags: [model]
|
|
summary: List model files with metadata
|
|
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
|
|
|
|
/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
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Users
|
|
# ---------------------------------------------------------------------------
|
|
/api/users:
|
|
get:
|
|
operationId: getUsers
|
|
tags: [user]
|
|
summary: Get user storage info
|
|
description: |
|
|
Returns user storage configuration. In single-user mode returns
|
|
`{"storage": "server", "migrated": true/false}`. In multi-user mode
|
|
returns `{"storage": "server", "users": {"user_id": "user_dir", ...}}`.
|
|
parameters:
|
|
- $ref: "#/components/parameters/ComfyUserHeader"
|
|
responses:
|
|
"200":
|
|
description: User info
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
storage:
|
|
type: string
|
|
description: Storage backend type (always "server")
|
|
migrated:
|
|
type: boolean
|
|
description: Whether migration from browser storage is complete (single-user)
|
|
users:
|
|
type: object
|
|
additionalProperties:
|
|
type: string
|
|
description: Map of user_id to directory name (multi-user)
|
|
post:
|
|
operationId: createUser
|
|
tags: [user]
|
|
summary: Create a new user (multi-user mode)
|
|
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: listUserdata
|
|
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/ListUserdataResponse"
|
|
"404":
|
|
description: Directory not found
|
|
|
|
/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
|
|
|
|
/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
|
|
post:
|
|
operationId: writeUserdataFile
|
|
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/UserDataResponse"
|
|
"409":
|
|
description: File exists and overwrite not set
|
|
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
|
|
|
|
/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/UserDataResponse"
|
|
"404":
|
|
description: Source file not found
|
|
"409":
|
|
description: Destination exists and overwrite not set
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Settings
|
|
# ---------------------------------------------------------------------------
|
|
/api/settings:
|
|
get:
|
|
operationId: getSettings
|
|
tags: [settings]
|
|
summary: Get all user settings
|
|
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
|
|
post:
|
|
operationId: updateSettings
|
|
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
|
|
|
|
/api/settings/{id}:
|
|
get:
|
|
operationId: getSetting
|
|
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
|
|
post:
|
|
operationId: updateSetting
|
|
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
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# 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"
|
|
|
|
/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
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Node Replacements
|
|
# ---------------------------------------------------------------------------
|
|
/api/node_replacements:
|
|
get:
|
|
operationId: getNodeReplacements
|
|
tags: [node]
|
|
summary: Get node replacement mappings
|
|
description: |
|
|
Returns a dictionary mapping deprecated or replaced node class names
|
|
to their replacement node information.
|
|
responses:
|
|
"200":
|
|
description: Replacement mappings
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Internal (x-internal: true)
|
|
# ---------------------------------------------------------------------------
|
|
/internal/logs:
|
|
get:
|
|
operationId: getInternalLogs
|
|
tags: [internal]
|
|
summary: Get server logs as text
|
|
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:
|
|
type: object
|
|
properties:
|
|
cols:
|
|
type: integer
|
|
rows:
|
|
type: integer
|
|
|
|
/internal/logs/subscribe:
|
|
patch:
|
|
operationId: subscribeToLogs
|
|
tags: [internal]
|
|
summary: Subscribe or unsubscribe a WebSocket client to log streaming
|
|
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: getInternalFiles
|
|
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
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# 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
|
|
|
|
/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: job_ids
|
|
in: query
|
|
schema:
|
|
type: string
|
|
x-runtime: [cloud]
|
|
description: "[cloud-only] Comma-separated UUIDs to filter assets by associated job."
|
|
- 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"
|
|
post:
|
|
operationId: createAsset
|
|
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"
|
|
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."
|
|
responses:
|
|
"201":
|
|
description: Asset created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/AssetCreated"
|
|
|
|
/api/assets/from-hash:
|
|
post:
|
|
operationId: createAssetFromHash
|
|
tags: [assets]
|
|
summary: Create an asset reference from an existing hash
|
|
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
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
user_metadata:
|
|
type: 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"
|
|
|
|
/api/assets/{id}:
|
|
get:
|
|
operationId: getAsset
|
|
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
|
|
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:
|
|
name:
|
|
type: string
|
|
description: New display name for the asset
|
|
user_metadata:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Custom user metadata to set
|
|
preview_id:
|
|
type: string
|
|
format: uuid
|
|
description: ID of the asset to use as the preview
|
|
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"
|
|
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
|
|
|
|
/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}/preview:
|
|
put:
|
|
operationId: setAssetPreview
|
|
tags: [assets]
|
|
summary: Set preview asset
|
|
description: Sets the preview asset for an existing asset. The preview_id must reference an existing 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:
|
|
- preview_id
|
|
properties:
|
|
preview_id:
|
|
type: string
|
|
format: uuid
|
|
description: ID of the asset to use as the preview
|
|
responses:
|
|
"200":
|
|
description: Preview set successfully
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/Asset"
|
|
"404":
|
|
description: Asset not found
|
|
delete:
|
|
operationId: clearAssetPreview
|
|
tags: [assets]
|
|
summary: Clear preview asset
|
|
description: Clears the preview asset link for an existing asset.
|
|
x-feature-gate: enable-assets
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
description: The asset ID.
|
|
required: true
|
|
schema:
|
|
type: string
|
|
format: uuid
|
|
responses:
|
|
"204":
|
|
description: Preview cleared
|
|
"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"
|
|
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"
|
|
|
|
/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"
|
|
|
|
/api/assets/tags/refine:
|
|
get:
|
|
operationId: refineAssetTags
|
|
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"
|
|
|
|
/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:
|
|
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/CloudJobStatus"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/api/job/{job_id}/status:
|
|
get:
|
|
operationId: getCloudJobStatus
|
|
tags: [queue]
|
|
summary: Get status of a cloud job
|
|
description: "[cloud-only] Returns the current execution status of a cloud job."
|
|
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/CloudJobStatus"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/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: getHistoryV2
|
|
tags: [history]
|
|
summary: Get paginated execution history (v2)
|
|
description: "[cloud-only] Returns a paginated list of execution history entries in the v2 format, with richer metadata than the legacy history endpoint."
|
|
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/HistoryV2Response"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/api/history_v2/{prompt_id}:
|
|
get:
|
|
operationId: getHistoryV2ByPromptId
|
|
tags: [history]
|
|
summary: Get v2 history for a specific prompt
|
|
description: "[cloud-only] Returns the v2 history entry for a specific prompt execution."
|
|
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/HistoryV2Entry"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/api/logs:
|
|
get:
|
|
operationId: getCloudLogs
|
|
tags: [system]
|
|
summary: Get cloud execution logs
|
|
description: "[cloud-only] Returns execution logs for the authenticated user's cloud jobs."
|
|
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/CloudLogsResponse"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Assets extensions (cloud)
|
|
# ---------------------------------------------------------------------------
|
|
/api/assets/download:
|
|
post:
|
|
operationId: downloadAssets
|
|
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:
|
|
"200":
|
|
description: Download initiated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
task_id:
|
|
type: string
|
|
description: Task ID for tracking progress via WebSocket
|
|
"400":
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/api/assets/export:
|
|
post:
|
|
operationId: exportAssets
|
|
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
|
|
required:
|
|
- asset_ids
|
|
properties:
|
|
asset_ids:
|
|
type: array
|
|
items:
|
|
type: string
|
|
format: uuid
|
|
description: IDs of assets to export
|
|
export_name:
|
|
type: string
|
|
description: Name for the export archive
|
|
responses:
|
|
"200":
|
|
description: Export initiated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
task_id:
|
|
type: string
|
|
export_name:
|
|
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"
|
|
|
|
/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"
|
|
|
|
/api/assets/from-workflow:
|
|
post:
|
|
operationId: createAssetsFromWorkflow
|
|
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
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Tags to apply to the created assets
|
|
responses:
|
|
"201":
|
|
description: Assets created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
assets:
|
|
type: array
|
|
items:
|
|
$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"
|
|
|
|
/api/assets/import:
|
|
post:
|
|
operationId: importAssets
|
|
tags: [assets]
|
|
summary: Import assets from external URLs
|
|
description: "[cloud-only] Imports one or more assets from external URLs into the cloud asset store."
|
|
x-runtime: [cloud]
|
|
requestBody:
|
|
required: true
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
required:
|
|
- imports
|
|
properties:
|
|
imports:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/AssetImportRequest"
|
|
description: Assets to import
|
|
responses:
|
|
"200":
|
|
description: Import initiated
|
|
content:
|
|
application/json:
|
|
schema:
|
|
type: object
|
|
properties:
|
|
assets:
|
|
type: array
|
|
items:
|
|
$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"
|
|
|
|
/api/assets/remote-metadata:
|
|
get:
|
|
operationId: getAssetRemoteMetadata
|
|
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/RemoteAssetMetadata"
|
|
"400":
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Custom nodes / hub (cloud)
|
|
# ---------------------------------------------------------------------------
|
|
/api/experiment/nodes:
|
|
get:
|
|
operationId: listCloudNodes
|
|
tags: [node]
|
|
summary: List installed custom nodes
|
|
description: "[cloud-only] Returns the list of custom node packages installed in the cloud runtime."
|
|
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
|
|
responses:
|
|
"200":
|
|
description: Custom node list
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudNodeList"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
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:
|
|
- 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: getCloudNode
|
|
tags: [node]
|
|
summary: Get details of an installed custom node
|
|
description: "[cloud-only] Returns details about a specific installed custom node package."
|
|
x-runtime: [cloud]
|
|
parameters:
|
|
- name: id
|
|
in: path
|
|
required: true
|
|
schema:
|
|
type: string
|
|
description: Custom node package ID
|
|
responses:
|
|
"200":
|
|
description: Node detail
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudNode"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
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: getHubAssetUploadUrl
|
|
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:
|
|
type: string
|
|
format: uri
|
|
description: Pre-signed upload URL
|
|
asset_url:
|
|
type: 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"
|
|
|
|
/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:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/HubLabel"
|
|
|
|
/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"
|
|
|
|
/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"
|
|
|
|
/api/hub/profiles/check:
|
|
get:
|
|
operationId: checkHubProfileUsername
|
|
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:
|
|
type: string
|
|
|
|
/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"
|
|
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:
|
|
type: 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/HubWorkflowList"
|
|
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"
|
|
|
|
/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/HubWorkflow"
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
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"
|
|
|
|
/api/hub/workflows/index:
|
|
get:
|
|
operationId: getHubWorkflowIndex
|
|
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"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# Workflows (cloud)
|
|
# ---------------------------------------------------------------------------
|
|
/api/workflows:
|
|
get:
|
|
operationId: listCloudWorkflows
|
|
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/CloudWorkflowList"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
post:
|
|
operationId: createCloudWorkflow
|
|
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/CloudWorkflow"
|
|
"400":
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/api/workflows/{workflow_id}:
|
|
get:
|
|
operationId: getCloudWorkflow
|
|
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/CloudWorkflow"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
patch:
|
|
operationId: updateCloudWorkflow
|
|
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/CloudWorkflow"
|
|
"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"
|
|
delete:
|
|
operationId: deleteCloudWorkflow
|
|
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"
|
|
|
|
/api/workflows/{workflow_id}/content:
|
|
get:
|
|
operationId: getCloudWorkflowContent
|
|
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"
|
|
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: forkCloudWorkflow
|
|
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/CloudWorkflow"
|
|
"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}/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: createCloudWorkflowVersion
|
|
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"
|
|
|
|
/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/CloudWorkflow"
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# 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: createAuthSession
|
|
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"
|
|
delete:
|
|
operationId: deleteAuthSession
|
|
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"
|
|
|
|
/api/auth/token:
|
|
post:
|
|
operationId: createAuthToken
|
|
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
|
|
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/AuthTokenResponse"
|
|
"400":
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/.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"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# 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/BillingBalance"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/api/billing/events:
|
|
get:
|
|
operationId: listBillingEvents
|
|
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/BillingEventList"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/api/billing/ops/{id}:
|
|
get:
|
|
operationId: getBillingOp
|
|
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/BillingOp"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/api/billing/payment-portal:
|
|
post:
|
|
operationId: createPaymentPortalSession
|
|
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"
|
|
|
|
/api/billing/plans:
|
|
get:
|
|
operationId: listBillingPlans
|
|
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"
|
|
|
|
/api/billing/preview-subscribe:
|
|
post:
|
|
operationId: previewSubscription
|
|
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/SubscriptionPreview"
|
|
"400":
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/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/BillingStatus"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/api/billing/subscribe:
|
|
post:
|
|
operationId: createSubscription
|
|
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/BillingSubscription"
|
|
"400":
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/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/BillingSubscription"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/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/BillingSubscription"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/api/billing/topup:
|
|
post:
|
|
operationId: topUpCredits
|
|
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/BillingBalance"
|
|
"400":
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# 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"
|
|
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
|
|
responses:
|
|
"201":
|
|
description: API key created
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/WorkspaceApiKeyCreated"
|
|
"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"
|
|
|
|
/api/workspace/api-keys/{id}:
|
|
delete:
|
|
operationId: deleteWorkspaceApiKey
|
|
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"
|
|
|
|
/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"
|
|
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:
|
|
- email
|
|
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/WorkspaceInvite"
|
|
"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"
|
|
|
|
/api/workspace/invites/{inviteId}:
|
|
delete:
|
|
operationId: deleteWorkspaceInvite
|
|
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"
|
|
|
|
/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"
|
|
|
|
/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"
|
|
|
|
/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: bulkRevokeMemberApiKeys
|
|
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"
|
|
|
|
/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"
|
|
|
|
/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"
|
|
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"
|
|
|
|
/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"
|
|
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"
|
|
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"
|
|
|
|
# ---------------------------------------------------------------------------
|
|
# 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:
|
|
type: object
|
|
required:
|
|
- message
|
|
properties:
|
|
message:
|
|
type: string
|
|
description: Feedback message
|
|
rating:
|
|
type: integer
|
|
minimum: 1
|
|
maximum: 5
|
|
description: Optional satisfaction rating
|
|
context:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Additional context metadata
|
|
responses:
|
|
"200":
|
|
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"
|
|
|
|
/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:
|
|
type: string
|
|
description: Filename of the paint strokes layer
|
|
nullable: true
|
|
painted:
|
|
type: string
|
|
description: Filename of the painted image layer
|
|
nullable: true
|
|
painted_masked:
|
|
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:
|
|
type: object
|
|
required:
|
|
- event_name
|
|
properties:
|
|
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"
|
|
|
|
/api/invites/{token}/accept:
|
|
post:
|
|
operationId: acceptInvite
|
|
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/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: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/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"
|
|
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:
|
|
- name
|
|
- value
|
|
properties:
|
|
name:
|
|
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/SecretMeta"
|
|
"400":
|
|
description: Bad request
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
|
|
/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/SecretMeta"
|
|
"401":
|
|
description: Unauthorized
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
"404":
|
|
description: Not found
|
|
content:
|
|
application/json:
|
|
schema:
|
|
$ref: "#/components/schemas/CloudError"
|
|
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/SecretMeta"
|
|
"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"
|
|
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"
|
|
|
|
/api/user:
|
|
get:
|
|
operationId: getCloudUser
|
|
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/CloudUser"
|
|
"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"
|
|
post:
|
|
operationId: publishUserdataFile
|
|
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:
|
|
type: 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"
|
|
|
|
/api/vhs/queryvideo:
|
|
get:
|
|
operationId: queryVhsVideo
|
|
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"
|
|
|
|
/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
|
|
description: "[cloud-only] Serves a video file from the output directory. Used by the frontend video player."
|
|
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"
|
|
|
|
/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"
|
|
|
|
|
|
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
|
|
description: |
|
|
Queue item tuple: [number, prompt_id, prompt, extra_data, outputs_to_execute, sensitive]
|
|
items: {}
|
|
prefixItems:
|
|
- type: number
|
|
description: Priority number
|
|
- type: string
|
|
format: uuid
|
|
description: prompt_id
|
|
- type: object
|
|
description: prompt graph
|
|
additionalProperties: true
|
|
- type: object
|
|
description: extra_data
|
|
additionalProperties: true
|
|
- type: array
|
|
description: outputs_to_execute (list of output node IDs)
|
|
items:
|
|
type: string
|
|
- type: object
|
|
description: sensitive data (may be omitted)
|
|
additionalProperties: true
|
|
|
|
QueueManageRequest:
|
|
type: object
|
|
description: Request to clear or delete from queue
|
|
properties:
|
|
clear:
|
|
type: boolean
|
|
description: If true, clear all pending items
|
|
delete:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of prompt IDs to delete from queue
|
|
|
|
# -------------------------------------------------------------------
|
|
# History
|
|
# -------------------------------------------------------------------
|
|
HistoryEntry:
|
|
type: object
|
|
description: A single execution history entry
|
|
properties:
|
|
prompt:
|
|
type: array
|
|
description: |
|
|
Prompt tuple: [number, prompt_id, prompt_graph, extra_data, output_node_ids]
|
|
items: {}
|
|
outputs:
|
|
type: object
|
|
description: Output data from execution keyed by node ID
|
|
additionalProperties: true
|
|
status:
|
|
type: object
|
|
description: Execution status (status_str, completed, messages, etc.)
|
|
additionalProperties: true
|
|
meta:
|
|
type: object
|
|
description: Metadata about the execution and nodes
|
|
additionalProperties: true
|
|
|
|
HistoryManageRequest:
|
|
type: object
|
|
description: Request to clear or delete history entries
|
|
properties:
|
|
clear:
|
|
type: boolean
|
|
description: If true, clear all history
|
|
delete:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Array of prompt IDs to delete from history
|
|
|
|
# -------------------------------------------------------------------
|
|
# Jobs
|
|
# -------------------------------------------------------------------
|
|
JobEntry:
|
|
type: object
|
|
description: Lightweight job data for list views
|
|
required:
|
|
- id
|
|
- status
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
description: Unique job identifier (same as prompt_id)
|
|
status:
|
|
type: string
|
|
description: Current job status
|
|
create_time:
|
|
type: number
|
|
description: Job creation timestamp
|
|
execution_start_time:
|
|
type: number
|
|
description: Workflow execution start timestamp
|
|
execution_end_time:
|
|
type: number
|
|
description: Workflow execution end timestamp
|
|
preview_output:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Primary preview output
|
|
outputs_count:
|
|
type: integer
|
|
description: Total number of output files
|
|
|
|
JobDetailResponse:
|
|
type: object
|
|
description: Full job details including workflow and outputs
|
|
required:
|
|
- id
|
|
- status
|
|
properties:
|
|
id:
|
|
type: string
|
|
format: uuid
|
|
status:
|
|
type: string
|
|
workflow:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Full ComfyUI workflow
|
|
outputs:
|
|
type: object
|
|
additionalProperties: true
|
|
description: Full outputs object from execution
|
|
execution_error:
|
|
$ref: "#/components/schemas/ExecutionError"
|
|
create_time:
|
|
type: number
|
|
update_time:
|
|
type: number
|
|
execution_start_time:
|
|
type: number
|
|
execution_end_time:
|
|
type: number
|
|
preview_output:
|
|
type: object
|
|
additionalProperties: true
|
|
outputs_count:
|
|
type: integer
|
|
execution_status:
|
|
type: object
|
|
additionalProperties: true
|
|
execution_meta:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
ExecutionError:
|
|
type: object
|
|
description: Detailed execution error from ComfyUI
|
|
properties:
|
|
node_id:
|
|
type: string
|
|
description: ID of the node that failed
|
|
node_type:
|
|
type: string
|
|
description: Type name of the node
|
|
exception_message:
|
|
type: string
|
|
description: Human-readable error message
|
|
exception_type:
|
|
type: string
|
|
description: Python exception type
|
|
traceback:
|
|
type: array
|
|
items:
|
|
type: string
|
|
description: Traceback lines
|
|
current_inputs:
|
|
type: object
|
|
additionalProperties: true
|
|
current_outputs:
|
|
type: object
|
|
additionalProperties: true
|
|
|
|
PaginationInfo:
|
|
type: object
|
|
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
|
|
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
|
|
width:
|
|
type: integer
|
|
nullable: true
|
|
description: "Original image width in pixels. Null for non-image assets or assets ingested before dimension extraction."
|
|
height:
|
|
type: integer
|
|
nullable: true
|
|
description: "Original image height in pixels. Null for non-image assets or assets ingested before dimension extraction."
|
|
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:
|
|
type: object
|
|
properties:
|
|
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
|
|
|
|
AssetImportRequest:
|
|
type: object
|
|
x-runtime: [cloud]
|
|
description: "[cloud-only] A single asset to import from an external URL."
|
|
required:
|
|
- url
|
|
properties:
|
|
url:
|
|
type: string
|
|
format: uri
|
|
description: URL of the asset to import
|
|
name:
|
|
type: string
|
|
description: Display name for the imported asset
|
|
tags:
|
|
type: array
|
|
items:
|
|
type: string
|
|
|
|
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
|
|
|
|
CloudNodeList:
|
|
type: object
|
|
x-runtime: [cloud]
|
|
description: "[cloud-only] Paginated list of installed custom node packages."
|
|
required:
|
|
- nodes
|
|
properties:
|
|
nodes:
|
|
type: array
|
|
items:
|
|
$ref: "#/components/schemas/CloudNode"
|
|
total:
|
|
type: integer
|
|
has_more:
|
|
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:
|
|
type: object
|
|
required:
|
|
- kty
|
|
- kid
|
|
- use
|
|
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
|
|
|
|
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: object
|
|
x-runtime: [cloud]
|
|
description: "[cloud-only] Overall billing and subscription status."
|
|
properties:
|
|
subscription:
|
|
$ref: "#/components/schemas/BillingSubscription"
|
|
balance:
|
|
$ref: "#/components/schemas/BillingBalance"
|
|
has_payment_method:
|
|
type: boolean
|
|
|
|
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
|
|
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
|
|
- email
|
|
- 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
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
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
|
|
- key
|
|
properties:
|
|
id:
|
|
type: string
|
|
name:
|
|
type: string
|
|
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
|
|
- email
|
|
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" |