hermes-agent/skills/creative/comfyui/references/rest-api.md

ComfyUI REST API Reference

ComfyUI exposes a REST API + WebSocket for workflow execution and management. Same API surface for local servers and Comfy Cloud (with auth differences).

Connection

	Local	Cloud
Base URL	http://127.0.0.1:8188	https://cloud.comfy.org
Auth	None (or bearer token)	X-API-Key header
WebSocket	ws://host:port/ws?clientId={uuid}	wss://cloud.comfy.org/ws?clientId={uuid}&token={API_KEY}
Output download	Direct bytes from /view	302 redirect → signed URL (use curl -L)

Workflow Execution

Submit Workflow

# Local
curl -X POST "http://127.0.0.1:8188/prompt" \
  -H "Content-Type: application/json" \
  -d '{"prompt": '"$(cat workflow_api.json)"', "client_id": "'"$(uuidgen)"'"}'

# Cloud
curl -X POST "https://cloud.comfy.org/api/prompt" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"prompt": '"$(cat workflow_api.json)"'}'

Response:

{"prompt_id": "abc-123-def", "number": 1, "node_errors": {}}

If node_errors is non-empty, the workflow has validation errors (missing nodes, bad inputs).

Check Job Status (Cloud)

curl -X GET "https://cloud.comfy.org/api/job/{prompt_id}/status" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY"

Status	Description
pending	Queued, waiting to start
in_progress	Currently executing
completed	Finished successfully
failed	Encountered an error
cancelled	Cancelled by user

Get History (Local)

# All history
curl -s "http://127.0.0.1:8188/history"

# Specific prompt
curl -s "http://127.0.0.1:8188/history/{prompt_id}"

Response contains outputs keyed by node ID with file references.

Download Output

# Local
curl -s "http://127.0.0.1:8188/view?filename=ComfyUI_00001_.png&subfolder=&type=output" \
  -o output.png

# Cloud (follow redirect)
curl -L "https://cloud.comfy.org/api/view?filename=ComfyUI_00001_.png&subfolder=&type=output" \
  -H "X-API-Key: $COMFY_CLOUD_API_KEY" \
  -o output.png

---

WebSocket Monitoring

Connect to WebSocket for real-time execution progress.

Connection

# Local
wscat -c "ws://127.0.0.1:8188/ws?clientId=MY-UUID"

# Cloud
wscat -c "wss://cloud.comfy.org/ws?clientId=MY-UUID&token=API_KEY"

Message Types (JSON)

Type	When	Key Fields
status	Queue change	queue_remaining
execution_start	Workflow begins	prompt_id
executing	Node running	node (ID), prompt_id
progress	Sampling steps	node, value, max
executed	Node output ready	node, output
execution_cached	Nodes skipped	nodes (list of IDs)
execution_success	All done	prompt_id
execution_error	Failure	exception_type, exception_message, traceback
execution_interrupted	Cancelled	prompt_id

When executing has node: null, the workflow is complete.

Binary Messages (Preview Images)

Format: [4B type][4B image_type: 1=JPEG, 2=PNG][image_data...]

---

File Upload

Upload Image

curl -X POST "http://127.0.0.1:8188/upload/image" \
  -F "image=@photo.png" \
  -F "type=input" \
  -F "overwrite=true"

Response: {"name": "photo.png", "subfolder": "", "type": "input"}

Upload Mask

curl -X POST "http://127.0.0.1:8188/upload/mask" \
  -F "image=@mask.png" \
  -F "type=input" \
  -F 'original_ref={"filename":"photo.png","subfolder":"","type":"input"}'

---

Node & Model Discovery

Object Info (All Nodes)

curl -s "http://127.0.0.1:8188/object_info" | python3 -m json.tool
# Returns all node types with input/output definitions

curl -s "http://127.0.0.1:8188/object_info/KSampler"
# Returns info for one specific node type

Models by Folder

curl -s "http://127.0.0.1:8188/models/checkpoints"
curl -s "http://127.0.0.1:8188/models/loras"
curl -s "http://127.0.0.1:8188/models/vae"
curl -s "http://127.0.0.1:8188/models/controlnet"
curl -s "http://127.0.0.1:8188/models/clip"
curl -s "http://127.0.0.1:8188/models/upscale_models"
curl -s "http://127.0.0.1:8188/models/embeddings"

Returns arrays of filenames (relative to model folder).

---

Queue Management

# View queue (running + pending)
curl -s "http://127.0.0.1:8188/queue"

# Clear all pending
curl -X POST "http://127.0.0.1:8188/queue" \
  -H "Content-Type: application/json" \
  -d '{"clear": true}'

# Delete specific items from queue
curl -X POST "http://127.0.0.1:8188/queue" \
  -H "Content-Type: application/json" \
  -d '{"delete": ["prompt_id_1", "prompt_id_2"]}'

# Cancel currently running job
curl -X POST "http://127.0.0.1:8188/interrupt"

---

System Management

# System stats (VRAM, RAM, GPU, versions)
curl -s "http://127.0.0.1:8188/system_stats"

# Free GPU memory
curl -X POST "http://127.0.0.1:8188/free" \
  -H "Content-Type: application/json" \
  -d '{"unload_models": true, "free_memory": true}'

---

ComfyUI Manager Endpoints (Optional)

These require ComfyUI-Manager installed.

# Install custom node from git repo
curl -X POST "http://127.0.0.1:8188/manager/queue/install" \
  -H "Content-Type: application/json" \
  -d '{"git_url": "https://github.com/user/comfyui-node.git"}'

# Check install queue status
curl -s "http://127.0.0.1:8188/manager/queue/status"

# Install model
curl -X POST "http://127.0.0.1:8188/manager/queue/install_model" \
  -H "Content-Type: application/json" \
  -d '{"url": "https://...", "path": "models/checkpoints", "filename": "model.safetensors"}'

---

POST /prompt Payload Format

{
  "prompt": {
    "3": {
      "class_type": "KSampler",
      "inputs": {
        "seed": 42,
        "steps": 20,
        "cfg": 7.5,
        "sampler_name": "euler",
        "scheduler": "normal",
        "denoise": 1.0,
        "model": ["4", 0],
        "positive": ["6", 0],
        "negative": ["7", 0],
        "latent_image": ["5", 0]
      }
    }
  },
  "client_id": "unique-uuid-for-ws-filtering",
  "extra_data": {
    "api_key_comfy_org": "optional-partner-node-key"
  }
}

• prompt: The workflow graph (API format)
• client_id: UUID for WebSocket event filtering
• extra_data.api_key_comfy_org: Required for paid partner nodes (Flux Pro, Ideogram, etc.)