Skip to main content
POST
/
r
/
workflows
/
{workflowId}
/
run
Execute a workflow by ID
curl --request POST \
  --url https://core.cyberun.cloud/api/v1/r/workflows/{workflowId}/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"
}
'
{
  "task_id": "019abc12-9012-7890-abcd-ef1234567896"
}

Documentation Index

Fetch the complete documentation index at: https://docs.cyberun.cloud/llms.txt

Use this file to discover all available pages before exploring further.

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

​
workflowId
string<uuid>
required

UUID of the workflow.

Example:

"019abc12-8901-7890-abcd-ef1234567895"

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:

FieldPurpose
keyThe key you use in the request body below
typestring / number / boolean / select / file
labelHuman-readable label for UI rendering
descriptionOptional description of what this parameter does
requiredIf true, you must provide a value
defaultValue used when the key is omitted (optional params only)
min / maxNumeric bounds (only for type: number)
optionsAllowed values list (only for type: select)
acceptAllowed 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:

  1. POST /r/files/presign with {"file_name": "photo.png", "file_size": 1048576, "content_type": "image/png"}
  2. Upload the file to the returned upload_url via HTTP PUT.
  3. 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, tw-tpe); 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"