mirror of
https://github.com/comfyanonymous/ComfyUI.git
synced 2026-05-09 16:52:32 +08:00
87878f354f
* Add cloud-runtime FE-facing operations to openapi.yaml
Add ~67 cloud-runtime FE-facing path operations to the core OpenAPI spec,
each tagged with x-runtime: [cloud] at the operation level. These operations
are served by the cloud runtime; the local runtime returns 404 for all of
these paths.
Domain groups added:
- Jobs / prompts: /api/job/*, /api/jobs/*/cancel, /api/prompt/*, etc.
- History v2: /api/history_v2, /api/history_v2/{prompt_id}
- Cloud logs: /api/logs
- Asset extensions: /api/assets/download, export, import, etc.
- Custom nodes: /api/experiment/nodes (cloud install/uninstall)
- Hub: /api/hub/profiles, /api/hub/workflows, /api/hub/labels, etc.
- Workflows: /api/workflows CRUD, versioning, fork, publish
- Auth/session: /api/auth/session, /api/auth/token, /.well-known/jwks.json
- Billing: /api/billing/balance, plans, subscribe, topup, etc.
- Workspace: /api/workspace/*, /api/workspaces/*
- User/settings/misc: /api/user, /api/secrets, /api/feedback, etc.
Also adds corresponding cloud-only component schemas (CloudJob, CloudWorkflow,
BillingPlan, Workspace, HubProfile, AuthSession, etc.), all tagged with
x-runtime: [cloud].
Spectral lint passes under the existing ruleset with zero new warnings.
* Add job_id field to Asset schema and deprecate prompt_id (#13736)
- Add job_id as a nullable UUID field to the Asset schema
- Mark prompt_id as deprecated with note pointing to job_id
- No x-runtime tag needed as both runtimes populate the field
* Add hash field to Asset schemas and deprecate asset_hash (#13738)
- Add 'hash' as a nullable string field to Asset and AssetUpdated schemas
- Mark 'asset_hash' as deprecated with a note pointing to 'hash'
- AssetCreated inherits 'hash' via allOf from Asset
- Spectral lint clean (no new warnings)
* Fix method drift on cloud-runtime endpoints
Three PUT operations were added that should be PATCH (cloud serves
PATCH for partial updates):
- /api/workflows/{workflow_id}
- /api/workspaces/{id}
- /api/workspace/members/{userId}
Two POST operations were added that should be GET (cloud serves GET
with query params):
- /api/assets/remote-metadata (url moves to query param)
- /api/files/mask-layers (response shape replaced — operation queries
related mask layer filenames, not file uploads)
* Add missing cloud-runtime operations and schemas
PR review surfaced operations the cloud runtime serves that weren't
covered by the initial spec push, plus one path family missed entirely.
New methods on existing paths:
- /api/auth/session: add POST (create session cookie) and DELETE (logout)
- /api/secrets/{id}: add GET (read metadata) and PATCH (update)
- /api/hub/profiles: add POST (create profile)
- /api/hub/workflows: add POST (publish to hub)
- /api/hub/workflows/{share_id}: add DELETE (unpublish)
- /api/workspaces/{id}: add DELETE (soft-delete workspace)
- /api/workspace/members/{user_id}/api-keys: add DELETE (bulk revoke)
- /api/workflows/{workflow_id}/versions: add POST (create new version)
- /api/userdata/{file}/publish: add GET (read publish info)
New path family:
- /api/tasks (GET list) and /api/tasks/{task_id} (GET detail) for the
background task framework
New component schemas (all tagged x-runtime: [cloud]):
CreateSessionResponse, DeleteSessionResponse, UpdateSecretRequest,
BulkRevokeAPIKeysResponse, CreateHubProfileRequest, PublishHubWorkflowRequest,
HubWorkflowDetail, AssetInfo, CreateWorkflowVersionRequest,
WorkflowVersionResponse, WorkflowPublishInfo, TaskEntry, TaskResponse,
TasksListResponse. Existing SecretMeta extended with provider and
last_used_at fields the cloud runtime actually returns.
New tag: task. Spectral lint passes with zero errors.
* Add job_id and prompt_id to AssetUpdated schema
Mirrors the Asset schema's deprecation pattern: prompt_id is marked
deprecated with a description pointing to job_id; job_id is the new
preferred field. PUT /api/assets/{id} responses can now carry both fields
consistent with the other Asset-returning endpoints.
* feat: add width and height fields to Asset schema (#13745)
Add nullable integer fields 'width' and 'height' to the Asset schema
in openapi.yaml. These expose original image dimensions in pixels for
clients that need pre-thumbnail size info. Both fields are null for
non-image assets or assets ingested before dimension extraction.
Co-authored-by: Matt Miller <MillerMedia@users.noreply.github.com>
* Remove /api/job/{job_id} and /api/job/{job_id}/outputs
These two paths are not actually served by the cloud runtime — they
return 404 with a redirect message pointing callers to the canonical
`/api/jobs/{job_id}` (plural). Declaring them with `x-runtime: [cloud]`
and a 200 response schema is incorrect.
`/api/job/{job_id}/status` stays — it is a real cloud-served endpoint.
Also drops the now-orphaned `CloudJob` and `CloudJobOutputs` component
schemas. `CloudJobStatus` is retained.
8079 lines
237 KiB
YAML
8079 lines
237 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}/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" |