Create 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>"
  ]
}
'

import requests

url = "https://api.comfycontrol.app/v1/runner"

payload = {
    "name": "<string>",
    "endpoint": "<string>",
    "headers": {},
    "tags": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>', endpoint: '<string>', headers: {}, tags: ['<string>']})
};

fetch('https://api.comfycontrol.app/v1/runner', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.comfycontrol.app/v1/runner",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'endpoint' => '<string>',
    'headers' => [
        
    ],
    'tags' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.comfycontrol.app/v1/runner"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"headers\": {},\n  \"tags\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.comfycontrol.app/v1/runner")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"headers\": {},\n  \"tags\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.comfycontrol.app/v1/runner")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"headers\": {},\n  \"tags\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "400": {},
  "401": {},
  "403": {},
  "id": "<string>",
  "user_id": "<string>",
  "name": "<string>",
  "status": "<string>",
  "endpoint": "<string>",
  "tags": [
    "<string>"
  ],
  "headers": {},
  "created_at": "<string>",
  "updated_at": "<string>"
}

POST

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>"
  ]
}
'

import requests

url = "https://api.comfycontrol.app/v1/runner"

payload = {
    "name": "<string>",
    "endpoint": "<string>",
    "headers": {},
    "tags": ["<string>"]
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({name: '<string>', endpoint: '<string>', headers: {}, tags: ['<string>']})
};

fetch('https://api.comfycontrol.app/v1/runner', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.comfycontrol.app/v1/runner",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    'name' => '<string>',
    'endpoint' => '<string>',
    'headers' => [
        
    ],
    'tags' => [
        '<string>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.comfycontrol.app/v1/runner"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"headers\": {},\n  \"tags\": [\n    \"<string>\"\n  ]\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.comfycontrol.app/v1/runner")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"headers\": {},\n  \"tags\": [\n    \"<string>\"\n  ]\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.comfycontrol.app/v1/runner")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"name\": \"<string>\",\n  \"endpoint\": \"<string>\",\n  \"headers\": {},\n  \"tags\": [\n    \"<string>\"\n  ]\n}"

response = http.request(request)
puts response.read_body

{
  "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

string

required

A descriptive name for your runner (1-100 characters).

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

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"}

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

string

required

Unique identifier (UUID) for the runner.

string

required

UUID of the user who owns this runner.

string

required

The runner’s name.

string

required

Current status of the runner. Values: active, disabled

string

required

The URL where the runner is accessible.

string[]

required

Array of tags associated with the runner.

object

required

The custom headers configured for this runner.

string

required

ISO 8601 timestamp when the runner was created.

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

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

error

Unauthorized - invalid or missing authentication token.

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

API Overview

Runners

Managed Runners

Workflows

Templates

User

Overview

Request Body

Response

Example Response

Error Responses

Notes

​Overview

​Request Body

​Response

​Example Response

​Error Responses

​Notes

Overview

Request Body

Response

Example Response

Error Responses

Notes