Create Workflow

Create Workflow

curl --request POST \
  --url https://api.comfycontrol.app/v1/workflow \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "tags": "<string>",
  "$text_parameter_name": "<string>",
  "#choice_parameter_name": "<string>"
}
'

import requests

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

payload = {
    "name": "<string>",
    "tags": "<string>",
    "$text_parameter_name": "<string>",
    "#choice_parameter_name": "<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>',
    tags: '<string>',
    $text_parameter_name: '<string>',
    '#choice_parameter_name': '<string>'
  })
};

fetch('https://api.comfycontrol.app/v1/workflow', 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/workflow",
  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>',
    'tags' => '<string>',
    '$text_parameter_name' => '<string>',
    '#choice_parameter_name' => '<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/workflow"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"tags\": \"<string>\",\n  \"$text_parameter_name\": \"<string>\",\n  \"#choice_parameter_name\": \"<string>\"\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/workflow")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"tags\": \"<string>\",\n  \"$text_parameter_name\": \"<string>\",\n  \"#choice_parameter_name\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"tags\": \"<string>\",\n  \"$text_parameter_name\": \"<string>\",\n  \"#choice_parameter_name\": \"<string>\"\n}"

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

{
  "400": {},
  "401": {},
  "403": {},
  "id": "<string>",
  "name": "<string>",
  "status": "<string>",
  "tags": [
    "<string>"
  ],
  "created_at": "<string>",
  "updated_at": "<string>",
  "started_at": "<string>",
  "completed_at": "<string>"
}

Create Workflow

curl --request POST \
  --url https://api.comfycontrol.app/v1/workflow \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "name": "<string>",
  "tags": "<string>",
  "$text_parameter_name": "<string>",
  "#choice_parameter_name": "<string>"
}
'

import requests

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

payload = {
    "name": "<string>",
    "tags": "<string>",
    "$text_parameter_name": "<string>",
    "#choice_parameter_name": "<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>',
    tags: '<string>',
    $text_parameter_name: '<string>',
    '#choice_parameter_name': '<string>'
  })
};

fetch('https://api.comfycontrol.app/v1/workflow', 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/workflow",
  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>',
    'tags' => '<string>',
    '$text_parameter_name' => '<string>',
    '#choice_parameter_name' => '<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/workflow"

	payload := strings.NewReader("{\n  \"name\": \"<string>\",\n  \"tags\": \"<string>\",\n  \"$text_parameter_name\": \"<string>\",\n  \"#choice_parameter_name\": \"<string>\"\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/workflow")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"name\": \"<string>\",\n  \"tags\": \"<string>\",\n  \"$text_parameter_name\": \"<string>\",\n  \"#choice_parameter_name\": \"<string>\"\n}")
  .asString();

require 'uri'
require 'net/http'

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

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  \"tags\": \"<string>\",\n  \"$text_parameter_name\": \"<string>\",\n  \"#choice_parameter_name\": \"<string>\"\n}"

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

{
  "400": {},
  "401": {},
  "403": {},
  "id": "<string>",
  "name": "<string>",
  "status": "<string>",
  "tags": [
    "<string>"
  ],
  "created_at": "<string>",
  "updated_at": "<string>",
  "started_at": "<string>",
  "completed_at": "<string>"
}

Overview

Create and execute a new ComfyUI workflow. This endpoint accepts multipart form data to support file uploads for workflow parameters.

Workflows are automatically scheduled on available runners based on tag matching. Ensure you have active runners with matching tags.

The API playground does not support file uploads. Use cURL, Postman, or your application code to test this endpoint.

Content Type

This endpoint requires multipart/form-data content type for file upload support. Maximum file size: 50MB per request

Request Parameters

string

required

A descriptive name for your workflow (1-200 characters).

file

required

A JSON file containing the ComfyUI workflow definition. This should be exported from ComfyUI or constructed programmatically.

string

Comma-separated list of tags for runner selection. The workflow will be scheduled on a runner with matching tags.Example: production,gpu-a100,image-generation

Dynamic Parameters

The workflow supports dynamic parameters using placeholders:

string

Text parameter - prefix the field name with $ followed by the placeholder name from your workflow.Example: $prompt for a text prompt

file

File parameter - prefix the field name with $ followed by the placeholder name, and include the file.Example: $input_image for an image file

string

Choice parameter - prefix the field name with # followed by the placeholder name.Example: #sampler for sampler selection

Learn more about placeholders and dynamic parameters in the Workflows concept page.

Response

string

required

Unique identifier (UUID) for the workflow.

string

required

The workflow’s name.

string

required

Initial status of the workflow (typically accepted).Possible values: accepted, uploaded, queued, running, completed, cancelled, invalid, failed

string[]

required

Array of tags associated with the workflow.

string

required

ISO 8601 timestamp when the workflow was created.

string

required

ISO 8601 timestamp when the workflow was last updated.

string

ISO 8601 timestamp when execution started (null initially).

string

ISO 8601 timestamp when execution completed (null initially).

Example Response

{
  "id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
  "name": "Text to Image Generation",
  "status": "accepted",
  "tags": ["production", "text2img"],
  "created_at": "2024-01-15T14:30:00Z",
  "updated_at": "2024-01-15T14:30:00Z",
  "started_at": null,
  "completed_at": null
}

cURL Example

Since the API playground doesn’t support file uploads, use this cURL command to test:

curl -X POST https://api.comfycontrol.app/v1/workflow \
  -H "Authorization: Bearer YOUR_API_TOKEN" \
  -F "name=My Workflow" \
  -F "tags=production,gpu" \
  -F "workflow_json=@/path/to/workflow.json" \
  -F '$prompt=A beautiful sunset over mountains' \
  -F '$input_image=@/path/to/image.png' \
  -F '#sampler=euler_ancestral'

Replace:

YOUR_API_TOKEN with your actual API token
/path/to/workflow.json with your ComfyUI workflow JSON file
/path/to/image.png with any input images (if needed)
Add dynamic parameters as needed with $ prefix for text/files, # prefix for choices

The -F flag automatically handles multipart/form-data with proper boundaries.

Workflow Lifecycle

After creation, the workflow goes through these states:

accepted - Workflow created and queued for processing
uploaded - Files uploaded to storage
queued - Waiting in runner’s queue
running - Currently executing on a runner
completed - Execution finished successfully
failed - Execution failed with an error
cancelled - Manually cancelled
invalid - Invalid workflow definition

Error Responses

error

Bad request - validation error in the request.Common causes:

Missing required fields (name, workflow_json)
Invalid workflow JSON structure
File size exceeds 50MB limit
Invalid tags format
Workflow parameter validation failed
No runner available with matching tags

error

Unauthorized - invalid or missing authentication token.

error

Forbidden - workflow parameter limit exceeded for your tier, or insufficient permissions.

Notes

Workflows are automatically assigned to runners based on tag matching
If no tags are specified, the workflow can run on any active runner
File parameters are stored securely and deleted after workflow completion
Use the subscribe endpoint to monitor workflow progress in real-time
You can create multiple workflows simultaneously
Workflow status updates can be monitored via the subscribe (SSE) endpoint or by polling the get endpoint
Use cURL, Postman, or application code for testing - the API playground doesn’t support file uploads

API Overview

Runners

Managed Runners

Workflows

Templates

User

Overview

Content Type

Request Parameters

Dynamic Parameters

Response

Example Response

cURL Example

Workflow Lifecycle

Error Responses

Notes

​Overview

​Content Type

​Request Parameters

​Dynamic Parameters

​Response

​Example Response

​cURL Example

​Workflow Lifecycle

​Error Responses

​Notes

Overview

Content Type

Request Parameters

Dynamic Parameters

Response

Example Response

cURL Example

Workflow Lifecycle

Error Responses

Notes