Skip to main content
POST
/
v1
/
runner
Create Runner
curl --request POST \
  --url https://api.comfycontrol.app/v1/runner \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "endpoint": "<string>",
  "headers": {},
  "tags": [
    "<string>"
  ]
}
'
{
  "400": {},
  "401": {},
  "403": {},
  "id": "<string>",
  "user_id": "<string>",
  "name": "<string>",
  "status": "<string>",
  "endpoint": "<string>",
  "tags": [
    "<string>"
  ],
  "headers": {},
  "created_at": "<string>",
  "updated_at": "<string>"
}

​
Overview

Register a new ComfyUI runner instance to execute workflows. Runners represent your own ComfyUI installations that ComfyControl can communicate with.
Your ComfyUI instance must be accessible via HTTP/HTTPS and have the ComfyUI API enabled.

​
Request Body

​
name
string
required
A descriptive name for your runner (1-100 characters).
​
endpoint
string
required
The URL where your ComfyUI instance is accessible. Must be a valid HTTP or HTTPS URL.Example: https://my-comfy.example.com or http://192.168.1.100:8188
​
headers
object
Custom HTTP headers to include when communicating with your runner. Use this for authentication or other custom headers. Optional - can be an empty object if no headers are needed.Example: {"Authorization": "Bearer token123", "X-Custom-Header": "value"}
​
tags
string[]
Array of tags for organizing and selecting runners (maximum 10 tags). Tags are used to match runners with workflows. Optional - can be an empty array.Example: ["production", "gpu-a100", "image-generation"]

​
Response

​
id
string
required
Unique identifier (UUID) for the runner.
​
user_id
string
required
UUID of the user who owns this runner.
​
name
string
required
The runner’s name.
​
status
string
required
Current status of the runner. Values: active, disabled
​
endpoint
string
required
The URL where the runner is accessible.
​
tags
string[]
required
Array of tags associated with the runner.
​
headers
object
required
The custom headers configured for this runner.
​
created_at
string
required
ISO 8601 timestamp when the runner was created.
​
updated_at
string
required
ISO 8601 timestamp when the runner was last updated.

​
Example Response

{
  "id": "550e8400-e29b-41d4-a716-446655440000",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Production GPU Runner",
  "status": "active",
  "endpoint": "https://my-comfy.example.com",
  "tags": ["production", "gpu-a100"],
  "headers": {
    "Authorization": "Bearer secret_token"
  },
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}
Example with empty headers and tags: 
{
  "id": "660e8400-e29b-41d4-a716-446655440001",
  "user_id": "7c9e6679-7425-40de-944b-e07fc1f90ae7",
  "name": "Development Runner",
  "status": "active",
  "endpoint": "http://192.168.1.100:8188",
  "tags": [],
  "headers": {},
  "created_at": "2024-01-15T10:30:00Z",
  "updated_at": "2024-01-15T10:30:00Z"
}

​
Error Responses

​
400
error
Bad request - validation error in the request body.Common causes:
  • Name is empty or too long
  • Invalid endpoint URL format
  • Too many tags (max 10)
  • Invalid headers format
​
401
error
Unauthorized - invalid or missing authentication token.
​
403
error
Forbidden - runner limit exceeded for your tier.

​
Notes

  • Runners are created with active status by default
  • The endpoint URL must be reachable from ComfyControl’s infrastructure