Execute a workflow by slug or slug@version

curl --request POST \
  --url https://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "parameters": {
    "prompt": "sunset over ocean",
    "width": 1024,
    "input_image": "inputs/019abc12-3456/550e8400-e29b/photo.png"
  },
  "dispatch_target": "agent",
  "target_pool": "team",
  "submitter_region": "us-east",
  "tool_type": "comfyui"
}
'

import requests

url = "https://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run"

payload = {
    "parameters": {
        "prompt": "sunset over ocean",
        "width": 1024,
        "input_image": "inputs/019abc12-3456/550e8400-e29b/photo.png"
    },
    "dispatch_target": "agent",
    "target_pool": "team",
    "submitter_region": "us-east",
    "tool_type": "comfyui"
}
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({
    parameters: {
      prompt: 'sunset over ocean',
      width: 1024,
      input_image: 'inputs/019abc12-3456/550e8400-e29b/photo.png'
    },
    dispatch_target: 'agent',
    target_pool: 'team',
    submitter_region: 'us-east',
    tool_type: 'comfyui'
  })
};

fetch('https://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run', 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://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run",
  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([
    'parameters' => [
        'prompt' => 'sunset over ocean',
        'width' => 1024,
        'input_image' => 'inputs/019abc12-3456/550e8400-e29b/photo.png'
    ],
    'dispatch_target' => 'agent',
    'target_pool' => 'team',
    'submitter_region' => 'us-east',
    'tool_type' => 'comfyui'
  ]),
  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://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run"

	payload := strings.NewReader("{\n  \"parameters\": {\n    \"prompt\": \"sunset over ocean\",\n    \"width\": 1024,\n    \"input_image\": \"inputs/019abc12-3456/550e8400-e29b/photo.png\"\n  },\n  \"dispatch_target\": \"agent\",\n  \"target_pool\": \"team\",\n  \"submitter_region\": \"us-east\",\n  \"tool_type\": \"comfyui\"\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://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"parameters\": {\n    \"prompt\": \"sunset over ocean\",\n    \"width\": 1024,\n    \"input_image\": \"inputs/019abc12-3456/550e8400-e29b/photo.png\"\n  },\n  \"dispatch_target\": \"agent\",\n  \"target_pool\": \"team\",\n  \"submitter_region\": \"us-east\",\n  \"tool_type\": \"comfyui\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run")

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  \"parameters\": {\n    \"prompt\": \"sunset over ocean\",\n    \"width\": 1024,\n    \"input_image\": \"inputs/019abc12-3456/550e8400-e29b/photo.png\"\n  },\n  \"dispatch_target\": \"agent\",\n  \"target_pool\": \"team\",\n  \"submitter_region\": \"us-east\",\n  \"tool_type\": \"comfyui\"\n}"

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

{
  "task_id": "019abc12-9012-7890-abcd-ef1234567896"
}

{
  "error_message": "resource not found"
}

{
  "error_message": "resource not found"
}

{
  "error_message": "resource not found"
}

{
  "error_message": "resource not found"
}

POST

workflows

slug

{workflowSlug}

run

Execute a workflow by slug or slug@version

curl --request POST \
  --url https://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "parameters": {
    "prompt": "sunset over ocean",
    "width": 1024,
    "input_image": "inputs/019abc12-3456/550e8400-e29b/photo.png"
  },
  "dispatch_target": "agent",
  "target_pool": "team",
  "submitter_region": "us-east",
  "tool_type": "comfyui"
}
'

import requests

url = "https://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run"

payload = {
    "parameters": {
        "prompt": "sunset over ocean",
        "width": 1024,
        "input_image": "inputs/019abc12-3456/550e8400-e29b/photo.png"
    },
    "dispatch_target": "agent",
    "target_pool": "team",
    "submitter_region": "us-east",
    "tool_type": "comfyui"
}
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({
    parameters: {
      prompt: 'sunset over ocean',
      width: 1024,
      input_image: 'inputs/019abc12-3456/550e8400-e29b/photo.png'
    },
    dispatch_target: 'agent',
    target_pool: 'team',
    submitter_region: 'us-east',
    tool_type: 'comfyui'
  })
};

fetch('https://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run', 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://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run",
  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([
    'parameters' => [
        'prompt' => 'sunset over ocean',
        'width' => 1024,
        'input_image' => 'inputs/019abc12-3456/550e8400-e29b/photo.png'
    ],
    'dispatch_target' => 'agent',
    'target_pool' => 'team',
    'submitter_region' => 'us-east',
    'tool_type' => 'comfyui'
  ]),
  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://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run"

	payload := strings.NewReader("{\n  \"parameters\": {\n    \"prompt\": \"sunset over ocean\",\n    \"width\": 1024,\n    \"input_image\": \"inputs/019abc12-3456/550e8400-e29b/photo.png\"\n  },\n  \"dispatch_target\": \"agent\",\n  \"target_pool\": \"team\",\n  \"submitter_region\": \"us-east\",\n  \"tool_type\": \"comfyui\"\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://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"parameters\": {\n    \"prompt\": \"sunset over ocean\",\n    \"width\": 1024,\n    \"input_image\": \"inputs/019abc12-3456/550e8400-e29b/photo.png\"\n  },\n  \"dispatch_target\": \"agent\",\n  \"target_pool\": \"team\",\n  \"submitter_region\": \"us-east\",\n  \"tool_type\": \"comfyui\"\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://core.cyberun.cloud/api/v1/r/workflows/slug/{workflowSlug}/run")

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  \"parameters\": {\n    \"prompt\": \"sunset over ocean\",\n    \"width\": 1024,\n    \"input_image\": \"inputs/019abc12-3456/550e8400-e29b/photo.png\"\n  },\n  \"dispatch_target\": \"agent\",\n  \"target_pool\": \"team\",\n  \"submitter_region\": \"us-east\",\n  \"tool_type\": \"comfyui\"\n}"

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

{
  "task_id": "019abc12-9012-7890-abcd-ef1234567896"
}

{
  "error_message": "resource not found"
}

{
  "error_message": "resource not found"
}

{
  "error_message": "resource not found"
}

{
  "error_message": "resource not found"
}

Authorizations

Authorization

string

header

required

User session JWT (Bearer ). Must be paired with the X-Team-ID request header on team-scoped endpoints so the server knows which team's resources to operate on.

Headers

X-Team-ID

string<uuid>

UUID of the team to scope the request to. Used by dual-auth endpoints (runtime + scoped management):

JWT callers MUST send it — a user may belong to multiple teams and the runtime cannot otherwise know which one to operate on. Missing header → 400.
Credential callers (sk-, dk-) can omit it because the team is derived from the credential row itself. Any value sent is ignored.

Example:

"019abc12-4567-7890-abcd-ef1234567891"

Path Parameters

workflowSlug

string

required

Workflow slug for runtime lookup. Use slug for the latest version or slug@version to reference an immutable workflow snapshot, e.g. text-to-image@2.

Maximum string length: 128

Pattern: ^[a-z0-9]+(?:-[a-z0-9]+)*(?:@[1-9][0-9]*)?$

Example:

"text-to-image@2"

Body

application/json

Request body to execute a workflow with optional parameter overrides.

Workflow run usage

Step 1 — Discover available parameters

Call GET /r/workflows/{workflowId} or GET /r/workflows/slug/{workflowSlug} to retrieve the workflow detail. To target a previous workflow version, use slug@version (for example, text-to-image@2). The parameters array contains ParameterDef entries that describe every user-configurable input. Each entry has:

Field	Purpose
`key`	The key you use in the request body below
`type`	`string` / `number` / `boolean` / `select` / `file`
`label`	Human-readable label for UI rendering
`description`	Optional description of what this parameter does
`required`	If `true`, you must provide a value
`default`	Value used when the key is omitted (optional params only)
`min` / `max`	Numeric bounds (only for `type: number`)
`options`	Allowed values list (only for `type: select`)
`accept`	Allowed MIME patterns (only for `type: file`, e.g. `image/*`)

Example parameters from a workflow detail response:

[
  {"key": "prompt", "node_id": "6", "field": "text", "type": "string",
   "label": "Positive Prompt", "required": true},
  {"key": "width",  "node_id": "5", "field": "width", "type": "number",
   "label": "Width", "min": 64, "max": 2048, "default": 512},
  {"key": "sampler", "node_id": "3", "field": "sampler_name", "type": "select",
   "label": "Sampler", "options": ["euler", "euler_ancestral", "dpmpp_2m"],
   "default": "euler"},
  {"key": "input_image", "node_id": "10", "field": "image", "type": "file",
   "label": "Input Image", "required": true, "accept": ["image/*"]}
]

Step 2 — Build the run request

Use the key values from the parameter definitions as keys in the parameters object:

POST /r/workflows/{workflowId}/run
{
  "parameters": {
    "prompt": "sunset over ocean",
    "width": 1024,
    "sampler": "dpmpp_2m"
  }
}

For type: file parameters, upload the file first, then pass the file_key:

POST /r/files/presign with {"file_name": "photo.png", "file_size": 1048576, "content_type": "image/png"}
Upload the file to the returned upload_url via HTTP PUT.
Pass the file_key as the parameter value:

{
  "parameters": {
    "input_image": "inputs/{team}/{uuid}/photo.png",
    "prompt": "enhance this photo"
  }
}

Step 3 — Validation rules

Unknown keys → 400 Bad Request (only keys from ParameterDef are accepted).
Missing required keys → 400 Bad Request.
Type mismatch → 400 Bad Request (e.g. string for a number parameter).
Out of range → 400 Bad Request (number outside min/max bounds).
Invalid select value → 400 Bad Request (value not in the options list).
File not uploaded → 400 Bad Request (file_key not found in S3).
File wrong team → 400 Bad Request (file_key must belong to the team).
File type rejected → 400 Bad Request (file MIME doesn't match accept pattern).
Omitted optional keys → the workflow's default value is used automatically.
Empty body {} → valid if no parameters are required (all have defaults).
Workflow with no parameters → send {} or omit parameters entirely.

Step 4 — Poll for results

The response contains a task_id. Poll status:

GET /r/tasks/{taskId}

When task_status is completed, fetch the output:

GET /r/tasks/{taskId}/result

parameters

object

Key-value map of parameter overrides. Keys must match the key field of a ParameterDef entry defined in the workflow's parameters array.

For type: file parameters, the value must be a file_key string obtained from POST /r/files/presign. Upload the file first, then pass the key here.

Retrieve available keys by calling GET /r/workflows/{workflowId} or GET /r/workflows/slug/{workflowSlug} and inspecting the parameters array in the response. Use workflowSlug@version to discover parameters for a previous workflow version.

Maximum 100 parameter keys per request.

Example:

{
  "prompt": "sunset over ocean",
  "width": 1024,
  "input_image": "inputs/019abc12-3456/550e8400-e29b/photo.png"
}

dispatch_target

enum<string>

Where to execute this task:

agent (default): Execute on a local BYOC agent.
comfy_cloud: Execute on ComfyUI Cloud (requires configured API key).

If omitted, the workflow's default_dispatch_target is used, falling back to agent.

Available options:

agent,

comfy_cloud

Example:

"agent"

target_pool

enum<string>

Dispatch pool for this task. Only meaningful when dispatch_target=agent.

team (default): route to an agent in the same team — the P2.1 behaviour.
community: route to any opted-in agent across teams via the Cyberun community pool. Submitting team does not need to opt in to consume; the serving agent does.

If omitted, defaults to team.

Available options:

team,

community

Example:

"team"

submitter_region

string

Submitter's declared geographic / network locality, used by the P3.1 scoring engine to favour region-matching agents when multiple candidates are eligible. Opaque user-supplied string (e.g. us-east, eu-central, ap-southeast); normalised server-side to lowercase + trimmed. Empty / omitted → scorer treats as unknown (neutral 0.5 region factor; no agent is disqualified). Has no effect on dispatch_target=comfy_cloud.

Maximum string length: 64

Example:

"us-east"

tool_type

enum<string>

Tool runtime used by this workflow:

comfyui: ComfyUI API workflow JSON (default, backward compatible).
nerfstudio: Nerfstudio 3DGS pipeline spec.

Available options:

comfyui,

nerfstudio

Example:

"comfyui"

Response

Task submitted

task_id

string<uuid>

required

ID of the created task. Use this to poll task status and results.

Example:

"019abc12-9012-7890-abcd-ef1234567896"

Execute a workflow by ID List tasks

Overview

Guides

Endpoints

Execute a workflow by slug or slug@version

Authorizations

Headers

Path Parameters

Body

Workflow run usage

Step 1 — Discover available parameters

Step 2 — Build the run request

Step 3 — Validation rules

Step 4 — Poll for results

Response