The most powerful and modular diffusion model GUI, api and backend with a graph/nodes interface. The fastest local inference engine in the world.
chore(openapi): sync shared API contract from cloud@5273c30 (#14266)
Comfy Org PR Botcb9f63941608
diff --git a/openapi.yaml b/openapi.yamlindex b7e21245f..2510f97d0 100644--- a/openapi.yaml+++ b/openapi.yaml@@ -3,11 +3,6 @@ components:Asset:description: Represents a user-owned asset (image, video, or other generated output).properties:- asset_hash:- deprecated: true- description: 'Deprecated: use hash instead. Blake3 hash of the asset content.'- pattern: ^blake3:[a-f0-9]{64}$- type: stringcreated_at:description: Timestamp when the asset was createdformat: date-time@@ -16,8 +11,12 @@ components:description: Display name of the asset. Mirrors name for backwards compatibility.nullable: truetype: string+ file_path:+ description: Relative path in global-namespace-root form (e.g. "models/checkpoints/flux.safetensors")+ nullable: true+ type: stringhash:- description: Blake3 hash of the asset content. Preferred over asset_hash.+ description: Blake3 hash of the asset content.pattern: ^blake3:[a-f0-9]{64}$type: stringid:@@ -139,17 +138,16 @@ components:AssetUpdated:description: Response returned when an existing asset is successfully updated.properties:- asset_hash:- deprecated: true- description: 'Deprecated: use hash instead. Blake3 hash of the asset content.'- pattern: ^blake3:[a-f0-9]{64}$- type: stringdisplay_name:description: Display name of the asset. Mirrors name for backwards compatibility.nullable: truetype: string+ file_path:+ description: Relative path in global-namespace-root form (e.g. "models/checkpoints/flux.safetensors")+ nullable: true+ type: stringhash:- description: Blake3 hash of the asset content. Preferred over asset_hash.+ description: Blake3 hash of the asset content.pattern: ^blake3:[a-f0-9]{64}$type: stringid:@@ -828,7 +826,11 @@ components:type: stringtype: objectPaginationInfo:- description: Offset/limit-based pagination metadata included in list responses.+ 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@@ -837,12 +839,19 @@ components:description: Items per pageminimum: 1type: 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: stringoffset:- description: Current offset (0-based)+ deprecated: true+ description: 'Current offset (0-based). Deprecated: use cursor-based pagination.'minimum: 0type: integertotal:- description: Total number of items matching filters+ description: Total number of items matching filters (may be 0 when using cursor pagination)minimum: 0type: integerrequired:@@ -1518,17 +1527,11 @@ paths:schema:default: truetype: boolean- - description: Filter assets by exact content hash. Preferred over asset_hash.+ - description: Filter assets by exact content hash.in: queryname: hashschema:type: string- - deprecated: true- description: 'Deprecated: use hash instead. Filter assets by exact content hash.'- in: query- name: asset_hash- schema:- type: string- description: |Opaque cursor for keyset pagination. Pass the `next_cursor` valuefrom the previous response to fetch the next page. When provided,@@ -1571,42 +1574,12 @@ paths:- filepost:description: |- Uploads a new asset to the system with associated metadata.- Supports two upload methods:- 1. Direct file upload (multipart/form-data)- 2. URL-based upload (application/json with source: "url")+ 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: uploadAsset+ operationId: createAssetrequestBody:content:- application/json:- schema:- properties:- name:- description: Display name for the asset (used to determine file extension)- type: string- preview_id:- description: Optional preview asset ID- format: uuid- type: string- tags:- description: Freeform tags for the asset. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.- items:- type: string- type: array- url:- description: HTTP/HTTPS URL to download the asset from- format: uri- type: string- user_metadata:- additionalProperties: true- description: Custom metadata to store with the asset- type: object- required:- - url- - name- type: objectmultipart/form-data:schema:properties:@@ -1614,6 +1587,10 @@ paths:description: The asset file to uploadformat: binarytype: string+ hash:+ description: Content hash of the file.+ pattern: ^(blake3|sha256):[a-f0-9]{64}$+ type: stringid:description: Optional asset ID for idempotent creation. If provided and asset exists, returns existing asset.format: uuid@@ -1629,10 +1606,8 @@ paths:format: uuidtype: stringtags:- description: Freeform tags for the asset. Common types include "models", "input", "output", and "temp", but any tag can be used in any order.- items:- type: string- type: array+ 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: stringuser_metadata:description: Custom JSON metadata as a stringtype: string@@ -1641,36 +1616,32 @@ paths:type: objectrequired: trueresponses:+ "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+ description: Asset created successfully (created_new=true)"400":content:application/json:schema:$ref: '#/components/schemas/ErrorResponse'- description: Invalid request (bad file, invalid URL, invalid content type, etc.)+ description: Invalid request (bad file, invalid content type, etc.)"401":content:application/json:schema:$ref: '#/components/schemas/ErrorResponse'description: Unauthorized- "403":- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- description: Source URL requires authentication or access denied- "404":- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- description: Source URL not found"413":content:application/json:@@ -1683,19 +1654,13 @@ paths:schema:$ref: '#/components/schemas/ErrorResponse'description: Unsupported media type- "422":- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- description: Download failed due to network error or timeout"500":content:application/json:schema:$ref: '#/components/schemas/ErrorResponse'description: Internal server error- summary: Upload a new asset+ summary: Create a new assettags:- file/api/assets/{id}:@@ -1730,7 +1695,7 @@ paths:application/json:schema:$ref: '#/components/schemas/ErrorResponse'- description: Asset cannot be deleted because it is referenced by another resource (e.g., workflow version)+ 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:@@ -1783,7 +1748,7 @@ paths:description: |Updates an asset's metadata. At least one field must be provided.Only name, mime_type, preview_id, and user_metadata can be updated.- For tag management, use the dedicated PUT /api/assets/{id}/tags endpoint.+ For tag management, use POST (add) and DELETE (remove) /api/assets/{id}/tags.operationId: updateAssetparameters:- description: Asset ID@@ -1982,76 +1947,6 @@ paths:summary: Add tags to assettags:- file- put:- description: Adds and removes tags from an asset in a single operation- operationId: updateAssetTags- parameters:- - description: Asset ID- in: path- name: id- required: true- schema:- format: uuid- type: string- requestBody:- content:- application/json:- schema:- description: At least one of add or remove must contain items. Empty arrays are allowed when the other array has items.- minProperties: 1- properties:- add:- description: Tags to add to the asset. Can be empty if remove has items.- items:- type: string- type: array- remove:- description: Tags to remove from the asset. Can be empty if add has items.- items:- type: string- type: array- type: object- required: true- responses:- "200":- content:- application/json:- schema:- $ref: '#/components/schemas/TagsModificationResponse'- description: Tags updated successfully- "400":- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- description: Invalid request- "401":- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- description: Unauthorized- "404":- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- description: Asset not found- "422":- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- description: Reserved tag validation error- "500":- content:- application/json:- schema:- $ref: '#/components/schemas/ErrorResponse'- description: Internal server error- summary: Update asset tags- tags:- - file/api/assets/from-hash:post:description: |@@ -2090,12 +1985,20 @@ paths:type: objectrequired: trueresponses:+ "200":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/AssetCreated'+ description: |+ Asset reference 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 reference created successfully+ description: Asset reference created successfully (created_new=true)"400":content:application/json:@@ -2887,7 +2790,21 @@ paths:- asc- desctype: string- - description: Pagination offset (0-based)+ - description: |+ Opaque cursor for keyset pagination. Pass the `next_cursor` value+ from a previous response to fetch the next page.+ Cursor pagination is supported only when `sort_by=create_time`+ (default). If `sort_by=execution_time`, `after` is ignored and+ offset/limit pagination is used.+ Cursors are opaque base64url payloads — clients should treat them+ as strings and not parse the contents.+ example: eyJzIjoiY3JlYXRlX3RpbWUiLCJ2IjoiMTcxNjIwMDAwMDAwMDAwMCIsImlkIjoiYTFiMmMzZDQtZTVmNi03YTg5LWIwYzEtZDJlM2Y0YTViNmM3In0+ in: query+ name: after+ schema:+ type: string+ - deprecated: true+ description: 'Pagination offset (0-based). Deprecated: prefer cursor-based pagination via `after`.'in: queryname: offsetschema:@@ -2909,6 +2826,12 @@ paths:schema:$ref: '#/components/schemas/JobsListResponse'description: Success - Jobs retrieved+ "400":+ content:+ application/json:+ schema:+ $ref: '#/components/schemas/ErrorResponse'+ description: Bad request (e.g. malformed pagination cursor)."401":content:application/json: