components: schemas: Asset: description: Represents a user-owned asset (image, video, or other generated output). properties: created_at: description: Timestamp when the asset was created format: date-time type: string display_name: description: Display name of the asset. Mirrors name for backwards compatibility. nullable: true type: string file_path: description: Relative path in global-namespace-root form (e.g. "models/checkpoints/flux.safetensors") nullable: true type: string hash: description: Blake3 hash of the asset content. pattern: ^blake3:[a-f0-9]{64}$ type: string id: description: Unique identifier for the asset format: uuid type: string is_immutable: description: Whether this asset is immutable (cannot be modified or deleted) type: boolean job_id: description: ID of the job that created this asset, if available format: uuid nullable: true type: string last_access_time: description: Timestamp when the asset was last accessed format: date-time type: string metadata: additionalProperties: true description: System-managed metadata from download sources (HuggingFace, CivitAI, etc.) - read-only, not user-modifiable readOnly: true type: object mime_type: description: MIME type of the asset type: string name: description: Name of the asset file type: string preview_id: description: ID of the preview asset if available format: uuid nullable: true type: string preview_url: description: URL for asset preview/thumbnail format: uri type: string size: description: Size of the asset in bytes format: int64 type: integer tags: description: Tags associated with the asset items: type: string type: array updated_at: description: Timestamp when the asset was last updated format: date-time type: string user_metadata: additionalProperties: true description: Custom user metadata for the asset type: object required: - id - name - created_at - updated_at type: object AssetCreated: allOf: - $ref: '#/components/schemas/Asset' - properties: created_new: description: Whether this was a new asset creation (true) or returned existing (false) type: boolean required: - created_new type: object description: Response returned when a new asset is successfully created. AssetInfo: description: Lightweight asset reference used in workflow publishing payloads. properties: id: description: Asset identifier. type: string in_library: description: Whether the caller already owns this asset. type: boolean model: description: Whether this asset is a model. type: boolean name: type: string preview_url: description: Signed URL for previewing the asset. type: string public: description: Whether this is a public (platform-provided) asset. type: boolean storage_url: type: string required: - id - name - preview_url - storage_url - model - public - in_library type: object AssetTagHistogramResponse: description: Histogram of tag counts used for refining asset search results. properties: tag_counts: additionalProperties: type: integer description: Map of tag names to their occurrence counts on matching assets example: checkpoint: 32 lora: 193 vae: 6 type: object required: - tag_counts type: object AssetUpdated: description: Response returned when an existing asset is successfully updated. properties: display_name: description: Display name of the asset. Mirrors name for backwards compatibility. nullable: true type: string file_path: description: Relative path in global-namespace-root form (e.g. "models/checkpoints/flux.safetensors") nullable: true type: string hash: description: Blake3 hash of the asset content. pattern: ^blake3:[a-f0-9]{64}$ type: string id: description: Asset ID format: uuid type: string job_id: description: ID of the job that created this asset, if available format: uuid nullable: true type: string mime_type: description: Updated MIME type of the asset type: string name: description: Updated name of the asset type: string tags: description: Tags associated with the asset items: type: string type: array updated_at: description: Timestamp of the update format: date-time type: string user_metadata: additionalProperties: true description: Updated custom metadata type: object required: - id - updated_at type: object CreateWorkflowRequest: description: Request body for creating a new saved workflow. properties: default_view: description: Default view mode enum: - workflow - app type: string description: description: Description of the workflow type: string forked_from_workflow_id: description: ID of the source workflow if forked type: string forked_from_workflow_version_id: description: ID of the source workflow version if forked type: string name: description: Display name for the workflow type: string workflow_json: additionalProperties: true description: The ComfyUI workflow JSON type: object required: - workflow_json type: object CreateWorkflowVersionRequest: description: Request body for creating a new version of a saved workflow. properties: base_version: description: The version number this change is based on (for optimistic concurrency) type: integer workflow_json: additionalProperties: true description: The updated ComfyUI workflow JSON type: object required: - base_version - workflow_json type: object ErrorResponse: description: Standard error response with a machine-readable code and human-readable message. properties: code: type: string details: additionalProperties: true description: Optional open object carrying structured, machine-readable context about the error (e.g. offending field names, validation specifics). Absent for most errors; consumers must not assume any particular shape. type: object message: type: string required: - code - message type: object ExecutionError: description: Detailed execution error information from ComfyUI properties: current_inputs: additionalProperties: true description: Input values at time of failure (empty object if not available) type: object current_outputs: additionalProperties: true description: Output values at time of failure (empty object if not available) type: object exception_message: description: Human-readable error message type: string exception_type: description: Python exception type (e.g., "RuntimeError") type: string node_id: description: ID of the node that failed type: string node_type: description: Type name of the node (e.g., "KSampler") type: string traceback: description: Array of traceback lines (empty array if not available) items: type: string type: array required: - node_id - node_type - exception_message - exception_type - traceback - current_inputs - current_outputs type: object FeedbackRequest: description: Request to submit user feedback properties: content: description: The feedback content or message type: string metadata: additionalProperties: true description: Additional metadata about the feedback type: object rating: description: User's rating of ComfyUI Cloud experience (1-5 stars) maximum: 5 minimum: 1 type: integer type: description: Type of feedback being submitted enum: - missing_nodes - general - missing_models type: string required: - type type: object FeedbackResponse: description: Response after submitting feedback type: object ForkWorkflowRequest: description: Request body for forking an existing workflow into the user's account. properties: name: description: Name for the forked workflow type: string source_version: description: Version number to fork from type: integer required: - source_version type: object GetUserDataResponseFull: description: List of user data file entries (each with path, size, and modification time) returned when full_info=true. items: $ref: '#/components/schemas/GetUserDataResponseFullFile' type: array GetUserDataResponseFullFile: description: Individual file entry within a full user data response. properties: modified: description: UNIX timestamp of the last modification in milliseconds. format: int64 type: integer path: description: File name or path relative to the user directory. type: string size: description: File size in bytes. type: integer type: object GlobalSubgraphData: description: Full data for a global subgraph blueprint properties: data: description: The full subgraph JSON data as a string type: string info: description: Additional information about the subgraph properties: node_pack: description: The node pack/module that provides this subgraph type: string required: - node_pack type: object name: description: Display name of the subgraph blueprint type: string source: description: Source type of the subgraph - "templates" for workflow templates or "custom_node" for custom node subgraphs type: string required: - source - name - info - data type: object GlobalSubgraphInfo: description: Metadata for a global subgraph blueprint (without full data) properties: data: description: The full subgraph JSON data (may be empty in list view) type: string info: description: Additional information about the subgraph properties: node_pack: description: The node pack/module that provides this subgraph type: string required: - node_pack type: object name: description: Display name of the subgraph blueprint type: string source: description: Source type of the subgraph - "templates" for workflow templates or "custom_node" for custom node subgraphs type: string required: - source - name - info type: object HistoryDetailEntry: description: History entry with full prompt data properties: meta: additionalProperties: true description: Metadata about the execution and nodes type: object outputs: additionalProperties: true description: Output data from execution (generated images, files, etc.) type: object prompt: description: Full prompt execution data properties: extra_data: additionalProperties: true description: Additional execution data type: object outputs_to_execute: description: Output nodes to execute items: type: string type: array priority: description: Execution priority format: double type: number prompt: additionalProperties: true description: The workflow nodes type: object prompt_id: description: The prompt ID type: string type: object status: additionalProperties: true description: Execution status and timeline information type: object type: object HistoryDetailResponse: additionalProperties: $ref: '#/components/schemas/HistoryDetailEntry' description: | Detailed execution history response for a specific prompt. Returns a dictionary with prompt_id as key and full history data as value. type: object HistoryEntry: description: History entry with prompt_id and execution data properties: create_time: description: Job creation timestamp (Unix timestamp in milliseconds) format: int64 type: integer meta: additionalProperties: true description: Metadata about the execution and nodes type: object outputs: additionalProperties: true description: Output data from execution (generated images, files, etc.) type: object prompt: description: Filtered prompt execution data (lightweight format) properties: extra_data: additionalProperties: true description: Additional execution data (workflow removed from extra_pnginfo) type: object priority: description: Execution priority format: double type: number prompt_id: description: The prompt ID type: string type: object prompt_id: description: Unique identifier for this prompt execution type: string status: additionalProperties: true description: Execution status and timeline information type: object workflow_id: description: UUID identifying the workflow graph definition type: string required: - prompt_id type: object HistoryManageRequest: additionalProperties: false description: Request to manage history operations properties: clear: description: If true, clear all history for the authenticated user type: boolean delete: description: Array of job IDs to delete from history items: type: string type: array type: object HistoryResponse: description: | Execution history response with history array. Returns an object with a "history" key containing an array of history entries. Each entry includes prompt_id as a property along with execution data. properties: history: description: Array of history entries ordered by creation time (newest first) items: $ref: '#/components/schemas/HistoryEntry' type: array required: - history type: object JobCancelResponse: description: Response for POST /api/jobs/{job_id}/cancel. Returned on both fresh cancels and idempotent no-ops. properties: cancelled: description: | True when a cancel event was successfully dispatched by this call. False when the job was already in a terminal or cancelling state, in which case the call is a no-op (still 200 — idempotent). type: boolean required: - cancelled type: object JobDetailResponse: description: Full job details including workflow and outputs properties: create_time: description: Job creation timestamp (Unix timestamp in milliseconds) format: int64 type: integer execution_error: allOf: - $ref: '#/components/schemas/ExecutionError' description: Detailed execution error from ComfyUI (only for failed jobs with structured error data) execution_meta: additionalProperties: true description: Node-level execution metadata (only for terminal states) type: object execution_status: additionalProperties: true description: ComfyUI execution status and timeline (only for terminal states) type: object id: description: Unique job identifier format: uuid type: string outputs: additionalProperties: true description: Full outputs object from ComfyUI (only for terminal states) type: object outputs_count: description: Total number of output files (omitted for non-terminal states) type: integer preview_output: additionalProperties: true description: Primary preview output (only for terminal states) type: object status: description: User-friendly job status enum: - pending - in_progress - completed - failed - cancelled type: string update_time: description: Last update timestamp (Unix timestamp in milliseconds) format: int64 type: integer workflow: additionalProperties: true description: | Full ComfyUI workflow (10-100KB, omitted if not available). Sensitive credentials are redacted before the response is returned: `extra_data.api_key_comfy_org`, when present, is replaced with the literal string `"[REDACTED]"`. The field is preserved (not removed) so existence checks still pass, but the value is not usable. type: object workflow_id: description: UUID identifying the workflow graph definition type: string required: - id - status - create_time - update_time type: object JobEntry: description: Lightweight job data for list views (workflow and full outputs excluded) properties: create_time: description: Job creation timestamp (Unix timestamp in milliseconds) format: int64 type: integer execution_end_time: description: Workflow execution completion timestamp (Unix milliseconds, only present for terminal states) format: int64 type: integer execution_error: allOf: - $ref: '#/components/schemas/ExecutionError' description: Detailed execution error from ComfyUI (only for failed jobs with structured error data) execution_start_time: description: Workflow execution start timestamp (Unix milliseconds, only present for terminal states) format: int64 type: integer id: description: Unique job identifier format: uuid type: string outputs_count: description: Total number of output files (omitted for non-terminal states) type: integer preview_output: additionalProperties: true description: Primary preview output (only present for terminal states) type: object status: description: User-friendly job status enum: - pending - in_progress - completed - failed - cancelled type: string workflow_id: description: UUID identifying the workflow graph definition type: string required: - id - status - create_time type: object JobStatusResponse: description: Job status information properties: assigned_inference: description: The inference instance assigned to this job (if any) nullable: true type: string created_at: description: When the job was created format: date-time type: string error_message: description: Error message if the job failed nullable: true type: string id: description: The job ID format: uuid type: string last_state_update: description: When the job status was last changed format: date-time type: string status: description: Current job status enum: - waiting_to_dispatch - pending - in_progress - completed - error - cancelled type: string updated_at: description: When the job was last updated format: date-time type: string required: - id - status - created_at - updated_at type: object JobsCancelRequest: additionalProperties: false description: Request to cancel multiple jobs by ID. properties: job_ids: description: Job identifiers (UUIDs) to cancel. items: format: uuid type: string maxItems: 100 minItems: 1 type: array required: - job_ids type: object JobsCancelResponse: description: Response for POST /api/jobs/cancel. properties: cancelled: description: | Job IDs for which a cancel event was successfully dispatched by this call. Jobs already in a terminal or cancelling state are idempotently skipped and will not appear here. items: type: string type: array required: - cancelled type: object JobsListResponse: description: Paginated list of jobs for the authenticated user. properties: jobs: description: Array of jobs ordered by specified sort field items: $ref: '#/components/schemas/JobEntry' type: array pagination: $ref: '#/components/schemas/PaginationInfo' required: - jobs - pagination type: object ListAssetsResponse: description: Paginated list of assets belonging to the authenticated user. properties: assets: description: List of assets matching the query items: $ref: '#/components/schemas/Asset' type: array has_more: description: Whether more assets are available beyond this page type: boolean next_cursor: description: | Opaque cursor to pass as the `after` query parameter to fetch the next page. Omitted from the response when there are no more results. type: string total: description: Total number of assets matching the filters type: integer required: - assets - total - has_more type: object ListTagsResponse: description: Paginated list of available asset tags. properties: has_more: description: Whether more tags are available type: boolean tags: description: List of tags items: $ref: '#/components/schemas/TagInfo' type: array total: description: Total number of tags type: integer required: - tags - total - has_more type: object ModelFile: description: Represents a model file with metadata properties: name: description: The filename of the model example: model.safetensors type: string pathIndex: description: Index of the path where this model is located example: 0 type: integer required: - name - pathIndex type: object ModelFolder: description: Represents a folder containing models properties: folders: description: List of paths where models of this type are stored example: - checkpoints items: type: string type: array name: description: The name of the model folder example: checkpoints type: string required: - name - folders type: object NodeInfo: description: Metadata describing a single ComfyUI node type and its inputs/outputs. properties: api_node: description: Whether this is an API node type: boolean category: description: Category of the node type: string deprecated: description: Whether the node is deprecated type: boolean description: description: Description of the node type: string display_name: description: Display name of the node type: string experimental: description: Whether the node is experimental type: boolean input: additionalProperties: true description: Input specifications for the node type: object input_order: additionalProperties: items: type: string type: array description: Order of inputs for display type: object name: description: Internal name of the node type: string output: description: Output types of the node items: type: string type: array output_is_list: description: Whether each output is a list items: type: boolean type: array output_name: description: Names of the outputs items: type: string type: array output_node: description: Whether this is an output node type: boolean output_tooltips: description: Tooltips for outputs items: type: string type: array python_module: description: Python module implementing the node type: string type: object PaginationInfo: description: | Pagination metadata included in list responses. Supports both legacy offset/limit pagination and cursor-based pagination. When cursor-based pagination is used, `next_cursor` is the primary pagination token and `offset`/`total` may be zero. properties: has_more: description: Whether more items are available beyond this page type: boolean limit: description: Items per page minimum: 1 type: integer next_cursor: description: | Opaque cursor for the next page. Pass this value as the `after` query parameter on the next request. Empty or absent when there are no more results. type: string offset: deprecated: true description: 'Current offset (0-based). Deprecated: use cursor-based pagination.' minimum: 0 type: integer total: description: Total number of items matching filters (may be 0 when using cursor pagination) minimum: 0 type: integer required: - offset - limit - total - has_more type: object PromptErrorResponse: additionalProperties: true description: Error response for ComfyUI prompt execution. type: object PromptInfo: description: Metadata about the currently running and queued prompts. properties: exec_info: properties: queue_remaining: description: Number of items remaining in the queue type: integer type: object type: object PromptRequest: description: Request body for submitting a ComfyUI workflow prompt for execution. properties: extra_data: additionalProperties: true description: Extra data to be associated with the prompt type: object front: description: If true, adds the prompt to the front of the queue type: boolean number: description: Priority number for the queue (lower numbers have higher priority) type: number partial_execution_targets: description: List of node names to execute items: type: string type: array prompt: additionalProperties: true description: The workflow graph to execute type: object workflow_id: description: UUID identifying the cloud workflow entity to associate with this job type: string workflow_version_id: description: UUID identifying the workflow version to associate with this job type: string required: - prompt type: object PromptResponse: description: Response returned after successfully queuing a workflow prompt. properties: node_errors: additionalProperties: true description: Any errors in the nodes of the prompt type: object number: description: Priority number in the queue type: number prompt_id: description: Unique identifier for the prompt execution format: uuid type: string type: object PublishWorkflowAssetsRequest: description: Request body for publishing workflow assets to the Hub. properties: asset_ids: description: IDs of assets (inputs and models) to snapshot. items: type: string type: array required: - asset_ids type: object PublishedWorkflowDetail: description: Full detail of a publicly published workflow on the Hub. properties: assets: description: Published assets with their library status for the caller. items: $ref: '#/components/schemas/AssetInfo' type: array listed: type: boolean name: description: Human-readable workflow name. type: string publish_time: format: date-time nullable: true type: string share_id: type: string workflow_id: type: string workflow_json: additionalProperties: true description: The workflow JSON content at publish time. type: object required: - share_id - workflow_id - name - listed - workflow_json - assets type: object QueueInfo: description: Queue information with pending and running jobs properties: queue_pending: description: Array of pending job items (ordered by creation time, oldest first) items: description: | Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata] - [0] job_number (integer): Position in queue (1-based) - [1] prompt_id (string): Job UUID - [2] workflow_json (object): Full ComfyUI workflow - [3] output_node_ids (array): Node IDs to return results from - [4] metadata (object): Contains {create_time: } items: {} maxItems: 5 minItems: 5 type: array type: array queue_running: description: Array of currently running job items items: description: | Queue item tuple format: [job_number, prompt_id, workflow_json, output_node_ids, metadata] - [0] job_number (integer): Position in queue (1-based) - [1] prompt_id (string): Job UUID - [2] workflow_json (object): Full ComfyUI workflow - [3] output_node_ids (array): Node IDs to return results from - [4] metadata (object): Contains {create_time: } items: {} maxItems: 5 minItems: 5 type: array type: array type: object QueueManageRequest: additionalProperties: false description: Request to manage queue operations properties: clear: description: If true, clear all pending jobs from the queue type: boolean delete: description: Array of job IDs to cancel; pending and running jobs transition to cancelled items: type: string type: array type: object QueueManageResponse: description: Response after a queue management action (delete or clear). properties: cleared: description: Whether the queue was cleared type: boolean deleted: description: Array of job IDs that were successfully cancelled items: type: string type: array type: object SystemStatsResponse: description: System statistics response properties: devices: items: properties: name: description: Device name type: string type: description: Device type type: string vram_free: description: Free VRAM in bytes type: number vram_total: description: Total VRAM in bytes type: number required: - name - type type: object type: array system: properties: argv: description: Command line arguments items: type: string type: array cloud_version: description: Cloud ingest service version (commit hash) type: string comfyui_frontend_version: description: ComfyUI frontend version (commit hash or tag) type: string comfyui_version: description: ComfyUI version type: string deploy_environment: description: How this ComfyUI instance is deployed (e.g. cloud, local-git, local-portable, local-desktop) type: string embedded_python: description: Whether using embedded Python type: boolean os: description: Operating system type: string python_version: description: Python version type: string pytorch_version: description: PyTorch version type: string ram_free: description: Free RAM in bytes type: number ram_total: description: Total RAM in bytes type: number workflow_templates_version: description: Workflow templates version type: string required: - os - python_version - embedded_python - comfyui_version - pytorch_version - argv - ram_total - ram_free type: object required: - system - devices type: object TagInfo: description: Metadata for a single tag that can be applied to assets. properties: count: description: Number of assets using this tag type: integer name: description: Tag name type: string required: - name - count type: object TagsModificationResponse: description: Response after adding, updating, or removing tags on an asset. properties: added: description: Tags that were successfully added (for add operation) items: type: string type: array already_present: description: Tags that were already present (for add operation) items: type: string type: array not_present: description: Tags that were not present (for remove operation) items: type: string type: array removed: description: Tags that were successfully removed (for remove operation) items: type: string type: array total_tags: description: All tags on the asset after the operation items: type: string type: array required: - total_tags type: object TaskEntry: description: Task data for list views properties: completed_at: description: When task completed or failed (null if not finished) format: date-time type: string create_time: description: Task creation timestamp format: date-time type: string id: description: Unique task identifier format: uuid type: string started_at: description: When task execution started (null if not started) format: date-time type: string status: description: Current task status enum: - created - running - completed - failed type: string task_name: description: Task type name (e.g., model_upload) type: string required: - id - task_name - status - create_time type: object TaskResponse: description: Full task details including payload and result properties: completed_at: description: When task completed or failed (null if not finished) format: date-time type: string create_time: description: Task creation timestamp format: date-time type: string error_message: description: Error message on failure (null if not failed) type: string id: description: Unique task identifier format: uuid type: string idempotency_key: description: Caller-provided key for idempotent task creation type: string payload: additionalProperties: true description: Task input data type: object result: additionalProperties: true description: Task output data (null if not completed) type: object started_at: description: When task execution started (null if not started) format: date-time type: string status: description: Current task status enum: - created - running - completed - failed type: string task_name: description: Task type name (e.g., model_upload) type: string update_time: description: Task last update timestamp format: date-time type: string required: - id - idempotency_key - task_name - payload - status - create_time - update_time type: object TasksListResponse: description: Paginated list of background tasks for the authenticated user. properties: pagination: $ref: '#/components/schemas/PaginationInfo' tasks: description: Array of tasks ordered by create_time items: $ref: '#/components/schemas/TaskEntry' type: array required: - tasks - pagination type: object UpdateWorkflowRequest: description: Request body for updating an existing saved workflow. properties: default_view: description: New default view mode enum: - workflow - app type: string description: description: New description type: string name: description: New display name type: string type: object UserDataResponseFull: description: User data listing entry with file metadata (path, size, modification time). properties: modified: description: UNIX timestamp of the last modification in milliseconds. format: int64 type: integer path: type: string size: type: integer type: object UserResponse: description: User information response properties: id: description: Firebase UID of the authenticated user type: string status: description: User status (always "active" for authenticated users) type: string required: - id - status type: object WorkflowForkedFrom: description: Reference to the parent workflow from which this workflow was forked. properties: workflow_id: type: string workflow_version_id: type: string type: object WorkflowListResponse: description: Paginated list of saved workflows. properties: data: items: $ref: '#/components/schemas/WorkflowResponse' type: array pagination: $ref: '#/components/schemas/PaginationInfo' required: - data - pagination type: object WorkflowPublishInfo: description: Publishing metadata for a workflow shared to the Hub. properties: assets: description: Published assets (inputs and models). items: $ref: '#/components/schemas/AssetInfo' type: array listed: type: boolean publish_time: format: date-time nullable: true type: string share_id: type: string workflow_id: type: string required: - workflow_id - share_id - listed - assets type: object WorkflowResponse: description: Full workflow entity including metadata and version history. properties: created_at: format: date-time type: string created_by: type: string default_view: enum: - workflow - app type: string description: type: string forked_from: $ref: '#/components/schemas/WorkflowForkedFrom' id: type: string latest_version: type: integer name: type: string updated_at: format: date-time type: string required: - id - latest_version - created_by - created_at - updated_at type: object WorkflowVersionContentResponse: description: Full workflow version including the serialized workflow JSON. properties: created_at: format: date-time type: string created_by: type: string dependency_asset_ids: items: type: string type: array id: type: string version: type: integer workflow_json: additionalProperties: true type: object required: - id - version - workflow_json - created_by - created_at type: object WorkflowVersionResponse: description: Metadata for a single workflow version. properties: created_at: format: date-time type: string created_by: type: string id: type: string latest_version: type: integer version: type: integer required: - id - version - latest_version - created_by - created_at type: object securitySchemes: ApiKeyAuth: description: | API key authentication. Keys are prefixed with 'comfyui-' and can be generated from user account settings. Example: 'comfyui-abc123...' in: header name: X-API-Key type: apiKey BearerAuth: bearerFormat: JWT description: | Firebase JWT token authentication. Obtain a token by authenticating with Firebase and pass it in the Authorization header. scheme: bearer type: http CookieAuth: description: | Session cookie authentication. Set automatically after successful login via the /api/auth/session endpoint. in: cookie name: session type: apiKey info: description: | API for ComfyUI - A powerful and modular UI for Stable Diffusion. This API allows you to interact with ComfyUI programmatically, including: - Retrieving prompt information - Retrieving node information license: name: GNU General Public License v3.0 url: https://github.com/Comfy-Org/ComfyUI/blob/master/LICENSE title: ComfyUI API version: 1.0.0 openapi: 3.0.3 paths: /api/assets: get: description: | Retrieves a paginated list of assets belonging to the authenticated user. Supports filtering by tags, name, metadata, and sorting options. operationId: listAssets parameters: - description: Filter assets that have ALL of these tags explode: false in: query name: include_tags schema: items: type: string type: array style: form - description: Exclude assets that have ANY of these tags explode: false in: query name: exclude_tags schema: items: type: string type: array style: form - description: Filter assets where name contains this substring (case-insensitive) in: query name: name_contains schema: type: string - description: JSON object for filtering by metadata fields in: query name: metadata_filter schema: type: string - description: Maximum number of assets to return (1-500) in: query name: limit schema: default: 20 maximum: 500 minimum: 1 type: integer - description: Number of assets to skip for pagination in: query name: offset schema: default: 0 minimum: 0 type: integer - description: Field to sort by in: query name: sort schema: default: created_at enum: - name - created_at - updated_at - size - last_access_time type: string - description: Sort order in: query name: order schema: default: desc enum: - asc - desc type: string - description: Whether to include public/shared assets in results in: query name: include_public schema: default: true type: boolean - description: Filter assets by exact content hash. in: query name: hash schema: type: string - description: | Opaque cursor for keyset pagination. Pass the `next_cursor` value from the previous response to fetch the next page. When provided, `offset` is ignored. Cursor pagination is only supported with `sort` values `created_at`, `updated_at`, `name`, or `size`; requests combining `after` with other sort fields return 400. The cursor must have been minted under the same `sort` value used in the follow-up request. in: query name: after schema: type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/ListAssetsResponse' description: Success - Assets returned "400": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid request parameters "401": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized "500": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error summary: List user assets tags: - file post: description: | Creates a new asset from a direct file upload (multipart/form-data) with associated metadata. If an asset with the same hash already exists, returns the existing asset. operationId: createAsset requestBody: content: multipart/form-data: schema: properties: file: description: The asset file to upload format: binary type: string hash: description: Content hash of the file. pattern: ^(blake3|sha256):[a-f0-9]{64}$ type: string id: description: Optional asset ID for idempotent creation. If provided and asset exists, returns existing asset. format: uuid type: string mime_type: description: MIME type of the asset (e.g., "image/png", "video/mp4") type: string name: description: Display name for the asset type: string preview_id: description: Optional preview asset ID. If not provided, images will use their own ID as preview. format: uuid type: string tags: description: JSON-encoded array of freeform tag strings, e.g. '["models","checkpoint"]'. Common types include "models", "input", "output", and "temp", but any tag can be used in any order. type: string user_metadata: description: Custom JSON metadata as a string type: string required: - file type: object required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/AssetCreated' description: | Asset already existed for this user (deduplicated by content hash); the existing asset is returned with created_new=false. "201": content: application/json: schema: $ref: '#/components/schemas/AssetCreated' description: Asset created successfully (created_new=true) "400": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Invalid request (bad file, invalid content type, etc.) "401": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized "413": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: File too large "415": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unsupported media type "500": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error summary: Create a new asset tags: - file /api/assets/{id}: delete: description: Deletes the asset record. operationId: deleteAsset parameters: - description: Asset ID in: path name: id required: true schema: format: uuid type: string responses: "204": description: Asset record deleted successfully "401": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized "404": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Asset not found "409": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: 'Asset cannot be deleted because it is referenced by another resource, e.g. a workflow version (error code: ASSET_IN_USE)' "500": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error summary: Delete asset tags: - file get: description: Retrieves detailed information about a specific asset operationId: getAssetById parameters: - description: Asset ID in: path name: id required: true schema: format: uuid type: string responses: "200": content: application/json: schema: $ref: '#/components/schemas/Asset' description: Asset details retrieved successfully "401": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized "404": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Asset not found "500": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error summary: Get asset details tags: - file put: description: | Updates an asset's metadata. At least one field must be provided. Only name, mime_type, preview_id, and user_metadata can be updated. For tag management, use POST (add) and DELETE (remove) /api/assets/{id}/tags. operationId: updateAsset parameters: - description: Asset ID in: path name: id required: true schema: format: uuid type: string requestBody: content: application/json: schema: minProperties: 1 properties: mime_type: description: Updated MIME type of the asset type: string name: description: New display name for the asset type: string preview_id: description: Updated preview asset ID format: uuid type: string user_metadata: additionalProperties: true description: Updated custom metadata type: object type: object required: true responses: "200": content: application/json: schema: $ref: '#/components/schemas/AssetUpdated' description: Asset updated successfully "400": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: | Invalid request — no fields provided, or `preview_id` is the zero UUID (`INVALID_PREVIEW_ID`). "401": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Unauthorized "404": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: | Asset not found — returned both when the asset being updated does not exist and when `preview_id` does not reference an asset accessible to the caller. "500": content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' description: Internal server error summary: Update asset metadata tags: - file /api/assets/{id}/content: get: description: | Returns the binary content of an asset by ID. The contract is the same across runtimes — "GET this path and you receive the asset's bytes" — but the mechanism differs: - **Local ComfyUI** streams the bytes directly (`200`, `application/octet-stream`). - **Cloud** does not proxy large files; it responds `302` with a `Location` redirect to a short-lived signed storage URL. Clients that follow redirects (browsers, `fetch`/XHR, ``/`