openapi: 3.0.3

info:

title: Comfy API v2

version: 2.0.0

description: "The official, versioned HTTP API for running ComfyUI workflows from\nexternal applications: upload inputs, submit a workflow, observe\nexecution, retrieve results.\n\nDesign principles:\n- **Poll-first.** Every capability is reachable via plain GET polling;\n the SSE stream is a live enhancement, never the source of truth.\n- **Everything is resumable.** Submission is idempotent; job state and\n outputs are retrievable by ID until `expires_at`.\n- **UUID identity, content-addressed dedup.** Assets are UUID-identified\n records over blobs keyed by a server-computed blake3 hash. The hash is\n nullable and may be computed lazily.\n- **Follow links, don't build URLs.** Responses embed follow-up URLs.\n\nAdditive changes only within v2; breaking changes require v3.\n"

servers:

- url: http://127.0.0.1:8189

description: Self-hosted (comfy-api-proxy)

- url: https://cloud.comfy.org

description: Comfy Cloud

- url: https://{deployment}.run.comfy.app

description: Serverless deployment

variables:

deployment:

description: DNS-safe deployment id (subdomain label). Staging uses {deployment}.stg.run.comfy.app.

default: dep-1234abcd-56ef-7890-abcd-ef1234567890

security:

- bearerAuth: []

- {}

tags:

- name: assets

description: UUID-identified records over content-addressed blobs.

- name: jobs

description: One execution of a workflow — durable, pollable, cancelable.

paths:

/api/v2/assets:

post:

operationId: postAssets

tags:

- assets

summary: Upload an asset (single-call multipart)

description: 'Single-call `multipart/form-data` upload. The platform streams the

x-streaming-upload: true

x-idempotency-key: recommended

parameters:

- $ref: '#/components/parameters/IdempotencyKey'

requestBody:

required: true

content:

multipart/form-data:

schema:

type: object

required:

- file

- content_type

- file_path

properties:

file:

type: string

format: binary

description: The raw bytes.

content_type:

type: string

example: image/png

description: The asset's media type. On Comfy Cloud it must be valid UTF-8, not blank, at most 255 bytes, must not start or end with whitespace, and must not contain control characters (C0, DEL, C1, U+2028, U+2029) or any invisible format or default-ignorable character (every Unicode general category Cf character, including the zero-width joiners and direction marks, and the other default-ignorable code points); otherwise the request is refused with 422 `invalid_body` before anything is stored. An accepted value is stored as sent.

file_path:

type: string

description: Placement path / filename (global-namespace-root form, e.g. `photo.png` or `models/checkpoints/x.safetensors`). On Comfy Cloud the last segment becomes the asset name, so it must be valid UTF-8, at most 255 bytes, must not start with `.`, and must not contain control characters (C0, DEL, C1, U+2028, U+2029) or invisible format and default-ignorable characters (Unicode general category Cf, which includes the bidi embedding, override and isolate controls, soft hyphen, zero-width space, word joiner, BOM and tag characters, plus the other default-ignorable code points such as U+034F, U+2065 and the Hangul fillers); otherwise the request is refused with 422 `invalid_body` before anything is stored. ZWNJ/ZWJ (U+200C, U+200D) and the direction marks U+200E, U+200F and U+061C are allowed, for right-to-left and emoji names, and so are the visible Arabic number signs (prepended concatenation marks such as U+0600) and variation selectors; the direction marks can still change how a name is displayed.

example: photo.png

expected_hash:

type: string

description: 'Optional client-computed blake3 (`blake3:<hex>`) of the bytes sent. Omit the part to skip verification: on Comfy Cloud and on a deployment a part sent empty is refused with 422 as malformed. Send it before `file`: nothing after the `file` field is read, so a trailing `expected_hash` is neither verified nor refused. Verified against the server-computed blake3 of the received bytes, not of the stored bytes; mismatch is rejected with 409 `hash_mismatch`. On serverless deployments no asset is minted and no existing asset''s retention is changed; elsewhere the upload is stored before the check, so the 409 returns no asset and a retry with the corrected expectation dedups onto it.'

example: blake3:9f8a1c0d...

tags:

type: array

items:

type: string

description: 'Category tags (e.g. `input`). A create carries at most 64 tags, each a non-empty UTF-8 string of at most 256 bytes (surrounding whitespace included) with no NUL byte. A deployment adds `input` to every asset and counts it, so it takes at most 63 of the caller''s own; the `model_type:` tags derived for a model asset are not counted. A tag set breaking a limit is refused with 422. The rest of this paragraph describes Cloud''s hosted API and a deployment, not the self-hosted proxy. Both cap the bytes of all `tags` parts sent before `file` combined: 8 KiB on Cloud''s hosted API (422 `invalid_body`) and 64 KiB on a deployment (422 `invalid_request`). The cap counts duplicates before they are removed and JSON escapes before they are decoded, and is checked before the count and 256-byte limits above, so a tag set within them can still be refused. A `quoted-printable` part is counted and read after it is decoded; a part in any other `Content-Transfer-Encoding` is read as sent, so a `base64` part is stored as one tag holding its encoded text, while a `7bit`, `8bit` or `binary` part is read like a part with no encoding. A part is read as a JSON array when it starts with `[` (after leading whitespace) and is valid JSON or continues, after optional whitespace, with `"`: `["a","b"]` is two tags, `[]` adds no tags (nor does an empty part), and a malformed array such as `[1]` or `["a` is refused with 422. Any other non-empty part is one bare tag, kept as literal text, so `foo\ud800` sent as a bare part is stored as written. Invalid UTF-8 in a `tags` part, or a lone surrogate escape (e.g. `\ud800`) in a JSON-array `tags` part, is refused with 422 (`invalid_body` on Cloud, `invalid_request` on a deployment).'

expires_in:

type: integer

minimum: 60

maximum: 604800

description: 'Optional retention override in seconds (60s–7d): the asset''s `expires_at` becomes now + `expires_in`, replacing the platform''s default retention. Implementations without configurable retention ignore it. The bounds apply to this override only — the platform default is operator-configured and may lie outside them.'

example: 86400

responses:

'201':

description: New blob stored; asset minted.

content:

application/json:

schema:

$ref: '#/components/schemas/Asset'

'200':

description: Bytes deduped to an existing blob; asset minted over it.

content:

application/json:

schema:

$ref: '#/components/schemas/Asset'

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'409':

description: '`hash_mismatch`.'

headers:

Retry-After:

$ref: '#/components/headers/RetryAfter'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'413':

description: The upload is over the body limit. On Comfy Cloud (200 MB, 200,000,000 bytes) and on deployment-scoped surfaces (110 MB, 110,000,000 bytes) the request declared a `Content-Length` over it; the server's body limit sends this before the upload is handled, so the body is not an `ErrorEnvelope` and its shape is not part of this contract. The self-hosted proxy instead refuses a file over its configured cap (100 MiB by default) with an `ErrorEnvelope` whose code is `payload_too_large`.

'422':

description: '`idempotency_key_reuse`, `input_blocked` (the bytes are already stored and flagged by content moderation, so `file_path` is not registered for them), `upload_timed_out` (the client stopped sending or sent too slowly; the server cannot recover the upload, so retry it from a faster connection), or validation failure — including a `tags` set over the limits above or a disallowed tag (`invalid_request` on a deployment or the self-hosted proxy; a deployment answers a body that is not `multipart/form-data` with a boundary with a plain 500 instead). On a deployment that includes a truncated `file` part: the body ends inside the part, before the delimiter that ends it. A body that stops right at that delimiter, without the final `--`, is not rejected: the part reads as complete and is stored. Comfy Cloud''s asset upload answers validation failure instead with `invalid_content_type` (the request is not `multipart/form-data` with a boundary), `invalid_body` (a malformed multipart body or upload field) or `validation_error` (the platform refused the upload, for example an image over the size cap or a disallowed tag). Cloud refuses a malformed multipart body with `invalid_body` when the fault is found before the `file` part. Cloud stops parsing at `file`, so parts after it are never read, and a body that ends inside the streamed file currently gets 500 `upstream_error` instead. The exception is an upload with `expected_hash`: if Cloud accepts the upload before the whole file is read, it reads the rest. A body that ends inside the `file` part, before its delimiter, then gets `invalid_body`, and a complete body gets 500 `upstream_error` instead of 201 or 409; in both cases the asset is already stored, holding only the part of the file read before the upload was accepted. `invalid_body` also covers `tags` parts over the 8 KiB combined cap described under `tags`, and a body sent without a declared length that is cut off at the body limit, as described for this operation. On Comfy Cloud and on a deployment, an `expected_hash` part that is present but empty is a malformed field (`invalid_body` on Comfy Cloud, `invalid_request` on a deployment), not an omitted hash.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'429':

$ref: '#/components/responses/RateLimited'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

/api/v2/assets/from-hash:

post:

operationId: assetFromHash

tags:

- assets

summary: Mint an asset over existing bytes (dedup fast-path)

description: 'Zero-byte fast-path: mints a new asset UUID over a blob the platform

requestBody:

required: true

content:

application/json:

schema:

type: object

required:

- hash

properties:

hash:

type: string

example: blake3:9f8a1c0d...

file_path:

type: string

description: 'Placement path / filename; its last segment becomes the asset name. On Comfy Cloud a `file_path` that fails path validation, or whose last segment breaks the `file_path` rules of `POST /api/v2/assets`, is answered with 404 `blob_not_found`, the same as an unknown hash. The UTF-8 rule cannot fire here: invalid UTF-8 bytes and lone surrogate escapes (`\ud800`) are replaced with U+FFFD when the JSON body is decoded, so such a name is stored with U+FFFD in their place.'

example: photo.png

tags:

type: array

items:

type: string

description: 'A create carries at most 64 tags, each a non-empty UTF-8 string of at most 256 bytes (surrounding whitespace included) with no NUL byte. A deployment adds `input` to every asset and counts it, so it takes at most 63 of the caller''s own; the `model_type:` tags derived for a model asset are not counted. A tag set breaking a limit is refused with 422. Invalid UTF-8 or a lone surrogate escape (e.g. `\ud800`) inside a JSON-encoded tag is not refused: JSON decoding replaces it with U+FFFD (3 bytes each), and the 256-byte limit applies to the replaced value.'

expires_in:

type: integer

minimum: 60

maximum: 604800

description: 'Optional retention override in seconds (60s–7d): the asset''s `expires_at` becomes now + `expires_in`, replacing the platform''s default retention. Implementations without configurable retention ignore it. The bounds apply to this override only — the platform default is operator-configured and may lie outside them.'

example: 86400

responses:

'201':

description: Asset minted over the existing blob.

content:

application/json:

schema:

$ref: '#/components/schemas/Asset'

'200':

description: An identical reference already existed; returned as-is.

content:

application/json:

schema:

$ref: '#/components/schemas/Asset'

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'404':

description: '`blob_not_found` — no blob the caller may mint from.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'422':

description: 'The `tags` or `expires_in` is malformed, `tags` breaks the limits above or holds a disallowed tag, or (on a deployment) the `file_path` is malformed: `invalid_request` on a deployment. On Cloud a tag with a malformed shape is `invalid_body`, and a refusal by the platform (for example a disallowed tag) is `validation_error`. Cloud answers a malformed `file_path` with 404 `blob_not_found` instead (see `file_path`). A deployment checks the tags even when an identical reference exists.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'429':

$ref: '#/components/responses/RateLimited'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

/api/v2/assets/by-hash/{hash}:

head:

operationId: headAssetByHash

tags:

- assets

summary: Existence check for a blob by blake3 hash

description: '`200` if the calling account can mint from this blob, `404` otherwise. Same account-scoping as `from-hash`; lets a client decide between the dedup fast-path and a full upload before sending bytes. Use the `hash` an upload returned: for an image whose location metadata was removed before storage, the client''s digest of the file it sent names no stored blob. A refusal answers its status with no body, so a `403`''s code is not readable here.'

parameters:

- $ref: '#/components/parameters/BlakeHash'

responses:

'200':

description: Blob present and mintable by the caller.

'404':

description: No blob the caller may mint from.

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'429':

$ref: '#/components/responses/RateLimited'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

/api/v2/assets/{id}:

get:

operationId: getAsset

tags:

- assets

summary: Asset metadata

description: Returns the asset object with a fresh short-lived `url` for the content. Re-fetching always yields fresh URLs.

parameters:

- $ref: '#/components/parameters/AssetId'

responses:

'200':

description: The asset.

content:

application/json:

schema:

$ref: '#/components/schemas/Asset'

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'404':

$ref: '#/components/responses/NotFound'

'429':

$ref: '#/components/responses/RateLimited'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

delete:

operationId: deleteAsset

tags:

- assets

summary: Delete an asset record

description: 'Deletes the asset RECORD. The underlying content-addressed blob is

parameters:

- $ref: '#/components/parameters/AssetId'

responses:

'204':

description: Record deleted.

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'404':

$ref: '#/components/responses/NotFound'

'409':

description: '`asset_in_use` — the record cannot be deleted while the platform still depends on it. Each surface defines its own holds (for example: a job''s outputs reference the record, or a content-moderation workflow requires it to be preserved); the response body deliberately never says which hold applies.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'429':

$ref: '#/components/responses/RateLimited'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

/api/v2/assets/{id}/content:

get:

operationId: getAssetContent

tags:

- assets

summary: Asset bytes

description: 'Serves the bytes directly on surfaces where the platform stores blobs

parameters:

- $ref: '#/components/parameters/AssetId'

- name: Range

in: header

required: false

schema:

type: string

description: Standard HTTP range, e.g. `bytes=0-1048575`.

responses:

'200':

description: The full content.

content:

application/octet-stream:

schema:

type: string

format: binary

'206':

description: Partial content for a ranged request.

content:

application/octet-stream:

schema:

type: string

format: binary

'302':

description: Redirect to a fresh signed URL (Cloud / serverless).

headers:

Location:

schema:

type: string

format: uri

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'404':

$ref: '#/components/responses/NotFound'

'416':

description: Range not satisfiable.

'429':

$ref: '#/components/responses/RateLimited'

'451':

description: '`content_blocked` on a deployment: content moderation flagged these bytes, so they are not served.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

/api/v2/jobs:

post:

operationId: postJobs

tags:

- jobs

summary: Submit a workflow for execution

description: 'Accepts the API-format workflow graph verbatim. Validation is

x-idempotency-key: recommended

parameters:

- $ref: '#/components/parameters/IdempotencyKey'

requestBody:

required: true

content:

application/json:

schema:

type: object

required:

- workflow

properties:

workflow:

type: object

description: API-format workflow graph, verbatim.

additionalProperties: true

extra_data:

type: object

description: 'Per-prompt ComfyUI `extra_data`, same shape as Comfy Cloud and local ComfyUI. Closed object: only the enumerated keys are accepted, keeping the contract fully typed. Forwarded to the worker per-prompt and excluded from idempotency comparison. On a deployment it is dispatch-only and never stored; on Comfy Cloud it is persisted with the prompt, because the worker needs it, and redacted on every path that returns a workflow to a caller.

additionalProperties: false

properties:

api_key_comfy_org:

type: string

description: API key for partner (API) nodes.

auth_token_comfy_org:

type: string

description: Session bearer token for partner (API) nodes — the equivalent of `api_key_comfy_org` for a caller authenticated by session rather than by key.

preview_method:

type: string

description: ComfyUI's preview method for this prompt, passed to ComfyUI as sent, which validates it. Used only for jobs sent by Comfy Cloud's editor; ignored for other callers.

extra_pnginfo:

type: object

description: ComfyUI's `extra_pnginfo` for this prompt, which carries the editor's workflow into saved outputs. Used only for jobs sent by Comfy Cloud's editor; ignored for other callers.

additionalProperties: true

metadata:

type: object

description: 'Your own labels for the job, such as which of your customers it ran for. At most 16 pairs. A key is 1 to 40 characters from `A-Z a-z 0-9 _ - .`; a value is a string of at most 256 bytes in UTF-8 (bytes, not characters: 200 `é` is 400 bytes) with no control character (U+0000 to U+001F, tab and newline included, and U+007F to U+009F) and no bidirectional embedding, override or isolate (U+202A to U+202E, U+2066 to U+2069). Anything else is refused `422` `metadata_invalid` and no job is created: a bad key or value is named in the message and in `details.key`, while more than 16 pairs is refused with the count and no `details`. A `metadata` that is not an object is refused `400` `invalid_request`; `null` is the same as none. Stored with the job, returned on it, and filterable on `GET /api/v2/jobs`. Set once, here: nothing changes it later. Only jobs sent to a deployment keep it today: Comfy Cloud refuses a non-empty `metadata` with `422` `metadata_not_supported`, and runs a job with empty or absent `metadata` as before.'

maxProperties: 16

additionalProperties:

type: string

description: 'At most 256 bytes in UTF-8, which is what the server counts. `maxLength` counts characters, so it is only an upper bound: a shorter value with multi-byte characters can still be refused.'

maxLength: 256

x-go-type: interface{}

example:

client: acme

batch: '2026-10-05'

responses:

'201':

description: Job created and queued.

content:

application/json:

schema:

$ref: '#/components/schemas/Job'

'400':

description: '`invalid_request`: `metadata` is not an object. A body that is not JSON at all, or whose `workflow` or `extra_data` is not an object, is a `400` too, answered by the request decoder before any of these checks, with a bare `message` body rather than this envelope.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'401':

$ref: '#/components/responses/Unauthorized'

'402':

description: '`insufficient_credits` (Cloud / serverless only).'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'403':

$ref: '#/components/responses/Forbidden'

'404':

description: '`not_found`: on a deployment''s address, no deployment there that the caller''s workspace owns.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'422':

description: '`invalid_workflow` (with per-node details), `workflow_format_ui`, `missing_asset`, `idempotency_key_reuse`, `metadata_invalid` (for a bad key or value, the message and `details.key` name the key; for more than 16 pairs, the message gives the count and there are no `details`), or `metadata_not_supported` (a surface that keeps no job labels yet).'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'429':

description: '`queue_full` (bounded queue depth reached) or, on deployment-scoped surfaces, `deployment_not_ready` (deployment still provisioning/starting) or `deployment_unavailable` (the deployment is ready but its GPU provider is not taking work on it yet), or `rate_limited` (the caller is past a request rate limit). Disambiguate by `error.code`; all four mean back off and retry after `Retry-After`.'

headers:

Retry-After:

$ref: '#/components/headers/RetryAfter'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

get:

operationId: listJobs

tags:

- jobs

summary: List jobs, newest first

description: 'Lists jobs newest first. At a deployment''s address, the jobs sent to

parameters:

- name: limit

in: query

required: false

description: 'Most jobs per page. Above 500 is read as 500; absent means 500. Not a positive integer: `422` `invalid_request`.'

schema:

type: integer

minimum: 1

- name: cursor

in: query

required: false

description: 'The previous page''s `next_cursor`, unchanged. Opaque: do not build or edit one. A cursor that is not well-formed is refused `400` `invalid_cursor`. Cursors are not signed, so a well-formed one is read as a position whether or not this list issued it.'

schema:

type: string

- name: metadata

in: query

required: false

style: deepObject

explode: true

description: Exact-match label filters, written `metadata[client]=acme`. Up to 3; all must match.

schema:

type: object

maxProperties: 3

additionalProperties:

type: string

example:

client: acme

responses:

'200':

description: One page of jobs, newest first.

content:

application/json:

schema:

$ref: '#/components/schemas/JobList'

'400':

description: '`invalid_metadata_filter` or `invalid_cursor`.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'404':

description: '`not_found`: on a deployment''s address, no deployment there that the caller''s workspace owns.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'422':

description: '`invalid_request`: `limit` is not a positive integer.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'429':

$ref: '#/components/responses/RateLimited'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

'501':

description: '`not_implemented`: this surface does not list jobs yet.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

/api/v2/jobs/{id}:

get:

operationId: getJob

tags:

- jobs

summary: Job status (the polling workhorse)

description: 'Returns the full job object: current status, the latest progress

parameters:

- $ref: '#/components/parameters/JobId'

responses:

'200':

description: The job.

content:

application/json:

schema:

$ref: '#/components/schemas/Job'

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'404':

$ref: '#/components/responses/NotFound'

'429':

$ref: '#/components/responses/RateLimited'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

/api/v2/jobs/{id}/workflow:

get:

operationId: getJobWorkflow

tags:

- jobs

summary: The workflow behind a job — authoring version if pinned, executed graph otherwise

description: "Returns the workflow behind a job. The response's `format` field says\nwhich of two different shapes `workflow` is in:\n\n- `format: save` — the original authoring workflow exactly as saved\n in the Comfy Cloud editor at the version the job ran, including\n canvas layout and frontend-only nodes (e.g. Note nodes; Get/Set\n nodes not yet expanded). Returned only when the job is pinned to a\n specific workflow version — see the \"when you get which\" note\n below.\n- `format: api` — the executed API-format prompt graph the job\n actually ran: frontend-only constructs are gone and Get/Set nodes\n are expanded. This is the same shape `POST /api/v2/jobs`'s\n `workflow` request field takes, and never includes the\n submission's `extra_data`, which can carry a live credential.\n\nAlways branch on `format`, never assume one or the other — which\nshape comes back depends on how the job was submitted, not on\nanything the caller controls per-request.\n\nA deliberate sub-resource, not a field on `GET /api/v2/jobs/{id}` —\nso the polling workhorse stays cheap and a caller pays for this only\nwhen it actually wants the workflow (for example, to recover what\nproduced a given output).\n\nTied to the job's own retention: this 404s under the same conditions\n`GET /api/v2/jobs/{id}` does (unknown, not-yours, or past its\nretention deadline) — there is no separate lifetime for the\nworkflow.\n\n**When you get which:** a job only carries a pinned workflow version\nwhen it was submitted with that association. Today that means jobs\nsubmitted from the Comfy Cloud frontend/editor. Jobs submitted\ndirectly through this v2 API (`POST /api/v2/jobs`) do not carry that\nassociation — v2 job submission has no version-linking fields yet —\nso they always get `format: api`. This is expected, not a bug: it\nwill change once v2 submission grows the same version pinning.\n\nA job pinned to a version also falls back to `format: api` if that\nversion, or the workflow it belongs to, is no longer readable by the\ncaller — for example the caller deleted the workflow since the job\nran. This is the same fallback as an unpinned job, and for the same\nreason: it is preferable to the alternative of erroring the whole\nrequest over data that is genuinely gone.\n"

parameters:

- $ref: '#/components/parameters/JobId'

responses:

'200':

description: The workflow graph.

content:

application/json:

schema:

$ref: '#/components/schemas/JobWorkflowResponse'

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'404':

$ref: '#/components/responses/NotFound'

'429':

$ref: '#/components/responses/RateLimited'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

/api/v2/jobs/{id}/logs:

get:

operationId: getJobLogs

tags:

- jobs

summary: What the run printed

description: 'Returns the job''s captured execution log. Fetched on demand: a log

parameters:

- $ref: '#/components/parameters/JobId'

responses:

'200':

description: The captured log.

content:

application/json:

schema:

$ref: '#/components/schemas/JobLogs'

'204':

description: This job has no log. A normal answer, not an error — see the description for the cases it covers.

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'404':

$ref: '#/components/responses/NotFound'

'429':

$ref: '#/components/responses/RateLimited'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'

/api/v2/jobs/{id}/events:

get:

operationId: getJobEvents

tags:

- jobs

summary: Live event stream (SSE)

description: 'Server-Sent Events stream of the job''s live state. On connect the

x-sse-events:

status:

description: Every lifecycle transition, including the initial state on connect and queue_position updates while queued.

schema: '#/components/schemas/StatusEvent'

progress:

description: Node- and step-level progress, throttled server-side (~2/s). Complete snapshot per event.

schema: '#/components/schemas/Progress'

preview:

description: In-progress preview image (JPEG, base64), throttled; server keeps only the most recent, pushed on connect.

schema: '#/components/schemas/PreviewEvent'

output:

description: 'Emitted the moment each output asset is committed, carrying the same `Output` object that appears on `job.outputs[]`. A latency optimization only: it lets a client render each result as it lands instead of waiting for the terminal `status` event. It is delivered best-effort over the live broadcast path — an output whose durable asset record is not yet resolvable when its node finishes may be delivered on a slightly later event or, failing that, only in the terminal `status` snapshot — so the authoritative, complete set of outputs is always `job.outputs[]` on `GET /api/v2/jobs/{id}` and on the terminal `status` event. A client must therefore treat these as additive hints and must not assume it receives one per output.'

schema: '#/components/schemas/Output'

log:

description: 'Selected execution log lines, carried while the run is still going. Best-effort diagnostics, and lossy by the same rule as the rest of this stream: lines emitted while a client was disconnected are gone and no `Last-Event-ID` replays them. The authoritative, complete log is the snapshot at `GET /api/v2/jobs/{id}/logs`, which a client re-reads after a terminal status to reconcile whatever it missed — on a surface that captures logs at all. Comfy Cloud does not, and answers `204` there for every job, so this event has nothing to be the live view of; see that operation for what a self-hosted deployment answers. NOT YET EMITTED by the server in the first iteration — reserved in the catalog so the wire contract is stable. Clients must not depend on receiving this event yet: to get a log today, stream to a terminal status and read the snapshot.'

x-sse-not-yet-emitted: true

schema: '#/components/schemas/LogEvent'

error:

description: 'Terminal event sent when the stream ends for a reason OTHER than the job reaching a terminal state — the credential the stream was opened with stopped being accepted (`credential_expired`, the common case for a short-lived Cloud JWT or OAuth access token that expires while a long job is still running), or the job stopped being accessible (`job_not_found`, `forbidden`). Transient upstream failures (5xx, network errors) do NOT end the stream — they are retried on the next poll. No `status` event follows it. Its whole purpose is to make an aborted stream distinguishable from a completed one: without it both simply close, and a client cannot tell "your job finished" from "you were cut off". On `credential_expired` the job itself is unaffected — refresh the credential and reopen the stream, or fall back to `GET /api/v2/jobs/{id}`. A serverless deployment sends only `job_not_found`.

schema: '#/components/schemas/ErrorEnvelope'

parameters:

- $ref: '#/components/parameters/JobId'

responses:

'200':

description: 'SSE stream; see `x-sse-events` for the event catalog. Sent with `Cache-Control: no-cache, no-store, no-transform` and `X-Accel-Buffering: no` so intermediaries neither cache, compress nor buffer the stream.'

content:

text/event-stream:

schema:

type: string

description: Stream of `event:`/`data:` frames. Data payloads are the JSON schemas listed in x-sse-events.

'401':

$ref: '#/components/responses/Unauthorized'

'403':

$ref: '#/components/responses/Forbidden'

'404':

$ref: '#/components/responses/NotFound'

'429':

description: '`too_many_streams` — the caller already has the maximum number of concurrent GET .../events streams open. Close an existing stream (or wait for one to reach a terminal status) before opening another; GET /api/v2/jobs/{id} remains available as a plain poll regardless of this limit. Or `rate_limited`, the caller past a request rate limit; retry after `Retry-After`.'

headers:

Retry-After:

$ref: '#/components/headers/RetryAfter'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'501':

description: '`not_implemented` — this deployment does not yet serve live event streaming. GET /api/v2/jobs/{id} remains available as a plain poll in the meantime.'

content:

application/json:

schema:

$ref: '#/components/schemas/ErrorEnvelope'

'503':

$ref: '#/components/responses/DeploymentLookupUnavailable'

'500':

$ref: '#/components/responses/UpstreamError'