ComfyUI workflows API

REST surface for the deployed ComfyUI workflows you publish via the ComfyUI-Runflow plugin. List, dispatch, inspect, and manage workflows + their inputs and outputs.

The ComfyUI workflows surface lives at /v1/comfyui-workflows/* and is intentionally not in the public OpenAPI bundle (the generated spec under API reference covers the core model + run surface only). The endpoints below are reachable and supported - this page is the canonical inline reference until they ship to the public spec.

For the end-to-end deploy flow, see Deploy a ComfyUI workflow. This page documents the bare API.

All endpoints require Authorization: Bearer $RUNFLOW_API_KEY. X-Organization-Id is optional and defaults to the key’s org. Reads need the comfyui-workflows:read scope; writes need comfyui-workflows:create, :edit, or :delete respectively.

Endpoints

Workflows

Method	Path	Purpose
GET	/v1/comfyui-workflows	Search/list workflows in your org (ANTLR filter, pagination, embeds).
POST	/v1/comfyui-workflows	Create a new workflow (with nested inputs/outputs/GPU models).
GET	/v1/comfyui-workflows/{id}	Fetch a workflow by UUID.
PATCH	/v1/comfyui-workflows/{id}	Partial update. Replace graph, swap GPU mode, toggle public.
DELETE	/v1/comfyui-workflows/{id}	Soft-delete a workflow.
GET	/v1/comfyui-workflows/{owner}/{slug}	Fetch by canonical {org}/{slug} path - mirrors the dispatch route.

Dispatch runs

Method	Path	Purpose
POST	/v1/comfyui-workflows/{owner}/{slug}/runs	Dispatch a workflow run. Same shape as POST /v1/models/.../runs.
GET	/v1/comfyui-workflows/{owner}/{slug}/runs	List recent runs for the workflow.

Inspect a dispatched run via GET /v1/runs/{id} (same generic run record as model runs).

Inputs and outputs

The Runflow Input / Output nodes in the ComfyUI graph map to first-class resources you can list and manage:

Method	Path	Purpose
GET	/v1/comfyui-workflows/{comfyui_workflow_id}/inputs	List a workflow’s inputs.
POST	/v1/comfyui-workflows/{comfyui_workflow_id}/inputs	Add an input definition.
GET	/v1/comfyui-workflows/{comfyui_workflow_id}/inputs/{id}	Fetch one.
PATCH	/v1/comfyui-workflows/{comfyui_workflow_id}/inputs/{id}	Update display name, description, defaults.
DELETE	/v1/comfyui-workflows/{comfyui_workflow_id}/inputs/{id}	Remove.
GET	/v1/comfyui-workflows/{comfyui_workflow_id}/outputs	List outputs.
POST	/v1/comfyui-workflows/{comfyui_workflow_id}/outputs	Add an output.
GET	/v1/comfyui-workflows/{comfyui_workflow_id}/outputs/{id}	Fetch one.
PATCH	/v1/comfyui-workflows/{comfyui_workflow_id}/outputs/{id}	Update.
DELETE	/v1/comfyui-workflows/{comfyui_workflow_id}/outputs/{id}	Remove.

Reference and stats

Method	Path	Purpose
GET	/v1/comfyui-workflows/categories	List flow categories (reference data).
GET	/v1/comfyui-workflows/categories/{code}	One category.
GET	/v1/comfyui-workflows/{owner}/{slug}/evaluation-issue-categories	Distinct (category, subcategory) pairs surfaced by evaluations for a workflow.
GET	/v1/comfyui-workflows/{comfyui_workflow_id}/evaluation-stats	Aggregate evaluation outcomes over a date range.
GET	/v1/comfyui-workflows/{comfyui_workflow_id}/run-performance-stats	Aggregate run performance (latency, completion, failures) over a date range.

Dispatch a run

POST /v1/comfyui-workflows/{owner}/{slug}/runs takes the same envelope you use for first-party models:

curl -X POST "https://api.runflow.io/v1/comfyui-workflows/{owner}/{slug}/runs" \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "input": {
      "prompt": "a sea otter holding a smooth pebble",
      "width": 1024,
      "height": 1024
    },
    "callback_url": "https://your-server.com/webhook",
    "client_ref": "ticket-4821"
  }'

Field	Type	Required	Notes
input	object	yes	Keyed by your workflow’s Runflow Input node input_ids. File slots accept runflow://assets/{uuid} or any https:// URL.
callback_url	string | null	no	POSTed once the run reaches a terminal state. See Callbacks.
client_ref	string | null	no	Max 255 chars. Echoed in webhook payloads. Not an idempotency key; not sent to the worker.
metadata	object | null	no	Arbitrary key/value attached to the run record.

Response is the minimal { "run_id": "...", "status": "queued" } envelope, not the full run record. Poll GET /v1/runs/{id}, whose status_code advances to a terminal state, or wait for the callback.

Create a workflow programmatically

Most teams use the ComfyUI-Runflow plugin to create workflows from a live ComfyUI install. For automation or CI, you can POST directly:

curl -X POST "https://api.runflow.io/v1/comfyui-workflows" \
  -H "Authorization: Bearer $RUNFLOW_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Background swap v2",
    "slug": "background-swap-v2",
    "workflow_json": { "...": "the full ComfyUI graph JSON" },
    "description": "Replace product background, preserve shadow.",
    "category_code": "image-to-image",
    "gpu_mode": "auto",
    "is_public": false
  }'

name and workflow_json are the only required fields. The full create validator accepts nested inputs[], outputs[], gpu_explicit_models[], custom_nodes[], models[], environment, and resources arrays.

Soft delete

DELETE /v1/comfyui-workflows/{id} marks the workflow deleted but preserves it for audit and rollback. Deleted workflows reject new runs (404 on the dispatch endpoint) but keep their historical run records reachable via the generic GET /v1/runs/{id}.

Related

Deploy a ComfyUI workflow

End-to-end plugin walkthrough.

Runs

Run record shape, polling, callbacks.

Webhooks

Org-level event delivery.

API reference

Public model + run surface (OpenAPI).