API reference

Routes

The proxy serves the Comfy API v2 under /api/v2. These are all the routes it registers. A GET route also answers HEAD.

There are no batch endpoints. One proxy fronts one ComfyUI, and a batch is a series of submits from the client. GET /api/v2/jobs, GET /api/v2/jobs/{id}/workflow, POST /api/v2/assets/from-path, DELETE /api/v2/assets/{id}, and GET /api/v2/health are proxy-local extensions that the vendored Comfy Cloud contract does not list.

Assets, uploads, and downloads are covered on Assets. This page covers jobs, health, and the conventions every route shares.

Authentication and origin checks

When a token is configured, every /api/v2/* request except GET /api/v2/health and OPTIONS preflights must carry it:

Authorization: Bearer <token>

A missing, malformed, or wrong token is 401 unauthorized. The token is compared in constant time.

An origin guard runs in front of auth on every request. A request with Sec-Fetch-Site: cross-site is 403 forbidden_origin, and so is a request whose Origin host does not match a loopback Host. Requests with no Origin header (curl, SDKs) pass. Origins allowlisted with cors_origins skip the guard and receive CORS headers. See Remote access and Configuration.

Error envelope

Every error the proxy writes has the same shape. details is null unless the error carries structured data.

{
  "error": {
    "code": "missing_asset",
    "message": "Unresolvable core/ASSET reference(s): nope",
    "details": {"missing_ids": ["nope"]}
  }
}

Match on code, not on message. The codes are the reference's exact strings.

Bounds

These are fixed in the binary and match the reference.

Health

GET /api/v2/health answers without calling ComfyUI and without a token, so a supervisor can probe it. upstream is the configured ComfyUI URL, not a reachability check.

curl -s http://127.0.0.1:8189/api/v2/health

{"status": "healthy", "upstream": "http://127.0.0.1:8188"}

Submit a job

POST /api/v2/jobs takes a JSON body and returns 201 with the job object.

curl -s http://127.0.0.1:8189/api/v2/jobs \
  -H 'Content-Type: application/json' \
  -H 'Idempotency-Key: 7d1f6c2e-5b0a-4e8f-9a51-3c2b8e7d4f10' \
  -d '{"workflow": {...}, "metadata": "demo", "priority": 3}'

{
  "id": "813f058f-80fc-4023-82bf-8c20fe3190ca",
  "status": "queued",
  "created_at": "2026-10-28T01:03:01.505579+00:00",
  "started_at": null,
  "completed_at": null,
  "expires_at": "2026-10-29T01:03:01.505579+00:00",
  "queue_position": null,
  "progress": null,
  "outputs": [],
  "error": null,
  "outputs_reused": false,
  "urls": {
    "self": "http://127.0.0.1:8189/api/v2/jobs/813f058f-80fc-4023-82bf-8c20fe3190ca",
    "events": "http://127.0.0.1:8189/api/v2/jobs/813f058f-80fc-4023-82bf-8c20fe3190ca/events",
    "cancel": "http://127.0.0.1:8189/api/v2/jobs/813f058f-80fc-4023-82bf-8c20fe3190ca/cancel"
  },
  "metadata": "demo",
  "priority": 3
}

The job id is a fresh UUID that the proxy also sends to ComfyUI as prompt_id and client_id.

Before the graph goes to ComfyUI, every core/ASSET reference in it is replaced with the filename ComfyUI's loaders expect. A reference names an uploaded asset id, an output asset id, or a content hash:

{"__type": "core/ASSET", "info": {"id": "31524f5f-055f-4bfc-9d5e-2418342382c2"}}

See Assets for how each kind resolves.

When ComfyUI rejects a graph, message is ComfyUI's error.message (or Workflow rejected. when it sent none) and details.node_errors is ComfyUI's node_errors object as sent, or {}:

{
  "error": {
    "code": "invalid_workflow",
    "message": "...",
    "details": {"node_errors": {...}}
  }
}

The proxy decodes workflow numbers exactly, so a 64-bit seed reaches ComfyUI unchanged. Object keys are re-encoded in sorted order.

Idempotency-Key

Idempotency-Key on POST /api/v2/jobs is single-use. The first submit with a key claims it, and any later submit with the same key is 422 idempotency_key_reuse. There is no replay of the first response: after a reuse error, poll the job or list jobs instead of resubmitting.

The claim is released only when ComfyUI definitely created no job, which is when it answered with a rejection. When ComfyUI could not be reached, the outcome is unknown, so the key stays claimed and a retry with it cannot submit twice.

Claims live in memory, up to 10,000 of them with the oldest evicted first. With --state-dir they are written to SQLite and survive a restart. See State and service.

Get a job

GET /api/v2/jobs/{id} is the authoritative view of a job. Each call reads ComfyUI's /history, then /queue if the job is not in history, and merges the result with the proxy's own record (created_at, metadata, priority).

{
  "id": "813f058f-80fc-4023-82bf-8c20fe3190ca",
  "status": "succeeded",
  "created_at": "2026-10-28T01:03:01.505579+00:00",
  "started_at": null,
  "completed_at": null,
  "expires_at": "2026-10-29T01:03:01.505579+00:00",
  "queue_position": null,
  "progress": null,
  "outputs": [
    {
      "node_id": "9",
      "name": "out.png",
      "type": "image",
      "content_type": "image/png",
      "size_bytes": 1553743,
      "id": "eyJqIjogIjgxM2Y...In0.A_8vZszyRfDl...",
      "hash": null,
      "url": "http://127.0.0.1:8189/api/v2/assets/eyJqIjogIjgxM2Y...In0.A_8vZszyRfDl.../content",
      "url_expires_at": "2026-10-29T01:03:01.734220+00:00",
      "job_id": "813f058f-80fc-4023-82bf-8c20fe3190ca"
    }
  ],
  "error": null,
  "outputs_reused": false,
  "urls": {"self": "...", "events": "...", "cancel": "..."},
  "metadata": "demo",
  "priority": 3
}

Job fields

A job ComfyUI no longer knows but the proxy recorded reads as expired. A job interrupted by a cancel reads as canceled.

Output fields

The base of every URL in a response is public_url when it is set, else the scheme and Host the client used. X-Forwarded-* headers are ignored, so a client cannot point emitted links at another origin. Behind a TLS-terminating reverse proxy, set public_url instead.

Value outputs

Some nodes return a value instead of writing a file: PreviewAny returns text, for example, and SaveText returns the text as well as the file it saves. ComfyUI's history holds these as raw strings under the node's key, and each becomes its own output entry: type from the key (text for text), content_type text/plain, size_bytes the length of the value in bytes, name <node>_<key>_<index>.txt, and an id and url like any other output. Its content is served from ComfyUI's history as text/plain; charset=utf-8 with X-Content-Type-Options: nosniff, so it is never rendered as HTML or run as script. A non-string value in that list is skipped. The Python proxy drops value outputs entirely (differences).

List jobs

GET /api/v2/jobs lists the jobs this proxy submitted, newest first, each resolved against ComfyUI as GET /jobs/{id} would.

curl -s 'http://127.0.0.1:8189/api/v2/jobs?limit=20&status=succeeded,failed'

{"jobs": [{"id": "813f058f-...", "status": "succeeded", ...}], "truncated": false}

There is no cursor. Each request walks the newest records and stops after 500 of them, because each one costs two ComfyUI reads. truncated: true means the walk stopped before it ran out of records, so more matches may exist further back. truncated: false means there are no more matches in memory.

The list covers the in-memory window only. With --state-dir, the newest 500 records reload at startup. Older records still answer GET /jobs/{id} but do not appear in the list.

Get a job's workflow

GET /api/v2/jobs/{id}/workflow returns the graph the job ran with, after core/ASSET references were resolved. It is the proxy's own stored copy, never ComfyUI's history copy, which carries the partner API key.

{"format": "api", "workflow": {"1": {"class_type": "EmptyImage", "inputs": {...}}}}

Cancel a job

POST /api/v2/jobs/{id}/cancel asks ComfyUI to cancel the job and returns the job object, as GET /jobs/{id} would. A running job reads canceling until the interrupt lands at the next node boundary, then canceled. Cancelling a finished job returns its terminal state. Poll the job or watch the event stream for the final status.

A job the proxy does not remember (after a restart without --state-dir) can still be cancelled while ComfyUI knows it.