> ## Documentation Index
> Fetch the complete documentation index at: https://docs.runflow.io/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/api) 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](/guides/comfyui-deploy). 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`](/api-reference/models/dispatch-a-run). |
| `GET` | `/v1/comfyui-workflows/{owner}/{slug}/runs` | List recent runs for the workflow. |
Inspect a dispatched run via [`GET /v1/runs/{id}`](/api-reference/runs/get-run) (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_id`s. 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](/concepts/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}`](/api-reference/runs/get-run), whose `status_code` advances to a terminal state, or wait for the callback.
## Create a workflow programmatically
Most teams use the [ComfyUI-Runflow plugin](/guides/comfyui-deploy) 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}`](/api-reference/runs/get-run).
## Related
End-to-end plugin walkthrough.
Run record shape, polling, callbacks.
Org-level event delivery.
Public model + run surface (OpenAPI).