Workflow format

A workflow is a list of steps and the connections between them. You can create one from code by sending that list to Create a workflow; Sushibelt lays it out as a graph on the canvas, where your team can open and edit it. This page is the full format: the request, how steps connect, the port types, and every node type.

The request#

A workflow belongs to an agent, inside a project. Pass agentId to add the workflow to an agent you already have, or projectId to create a new agent for it. In the app, both ids are in the address bar when you open an agent: /your-team/workspace/PROJECT_ID/AGENT_ID/canvas.

When you create a new agent, or add to an agent that has no active workflow, the new workflow becomes the one Run an agent runs. Adding a workflow to an agent that already has an active one leaves it unchanged.

Steps#

Each step is one node on the canvas.

Connecting steps#

A step's inputs list the steps it reads from. A node has named ports, called handles: inputs on one side, outputs on the other. There are two ways to connect:

• By key alone, such as "inputs": ["prompt"]: connects the other step's first output to this step's first input. Right for most nodes, which have one of each.
• With handles, such as { "from": "style", "targetHandle": "input-b" }: names the ports, for a node with more than one input or output.

The handle ids of every node are in the node types table below.

Port types#

Every handle carries a type, which decides what may connect to it.

What may connect to what#

• An output connects to an input of the same type.
• An any input takes every output, and an any output connects to every input.
• A same output carries the type of whatever reached the node's pass-through input, and is checked as that type.
• An input that lists several kinds, such as a delivery step's asset, takes any of them.
• number and num are the same type, and so are model3d and mesh.

For each input type, the outputs it takes besides any and same:

Validation#

A workflow is checked when you create it and again every time it runs, by the same rules the canvas uses. Creating one that fails answers 422; so does starting a run of one. The rules:

• Every step has a key, unique in the request, and a known type.
• Every connection names a key in the same request.
• No node with ports is left unconnected.
• Every required input is connected.
• Every required setting is filled, such as a Text node's text or a Prompt builder's template, unless a connection supplies it.
• Every connection joins types that fit, by the rules above.
• There are no loops: a step cannot depend on itself through other steps.
• No step uses a node type that cannot run (see Older type ids).

The answer lists each problem in errors, each with a message naming the node and, usually, its nodeId. A problem with the step list itself — an unknown type, a repeated key, a connection to no step — answers with a single error instead.

Settings#

A step's config holds its settings: the same values the inspector on the canvas shows. The ones you are most likely to set from code:

A complete example#

Two pieces of text joined into a prompt, made into an image, and shown in a gallery. The subject is exposed as an input named subject, so each run can change it.

curl -X POST "https://app.sushibelt.ai/api/v1/workflows" \
  -H "Authorization: Bearer $SUSHIBELT_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Fox in oils",
    "projectId": "YOUR_PROJECT_ID",
    "steps": [
      {
        "key": "subject",
        "type": "TextEntry",
        "config": {
          "text": "a red fox",
          "apiInputKey": "subject"
        }
      },
      {
        "key": "style",
        "type": "TextEntry",
        "config": {
          "text": "as an oil painting"
        }
      },
      {
        "key": "prompt",
        "type": "PromptBuilder",
        "config": {
          "template": "{{input-a}}, {{input-b}}"
        },
        "inputs": [
          {
            "from": "subject",
            "targetHandle": "input-a"
          },
          {
            "from": "style",
            "targetHandle": "input-b"
          }
        ]
      },
      {
        "key": "image",
        "type": "DiffusionWorker",
        "inputs": [
          "prompt"
        ]
      },
      {
        "key": "preview",
        "type": "ImageGallery",
        "inputs": [
          "image"
        ]
      }
    ]
  }'

{
  "workflowId": "3f1c9a52-8d4e-4b7a-9c61-2e5f0d7a1b90",
  "agentId": "5e0b7c3d-2a61-4f8e-b9d4-07c1a6e2f853",
  "projectId": "00000000-0000-0000-0000-000000000000",
  "stepsCount": 5
}

Then run it with { "inputs": { "subject": "a white wolf" } }. See Pass inputs to a run.

Node types#

Every node the canvas offers, grouped as the canvas groups them. The type is what you send; the name under it is what the canvas calls it. Each row lists the node's input and output handles with their port types.

Start#

Bring something in to work with.

2D#

Generate, guide, enlarge and cut out pictures.

Maps#

Depth and material maps from a picture.

3D#

Meshes from pictures, made game-ready.

Motion#

Skeletons and animation for a mesh.

Audio#

Speech and sound.

Text#

Write, describe, template and embed text.

Logic#

Route, repeat and reshape data.

Show & send#

Look at results, or deliver them.

Older type ids#

The API also accepts these type ids, so that older workflows keep working. Do not use them in new workflows: they are not on the canvas, and some are refused when a run starts.

InputStage, ProcessingStage, ExportStage, Prompt, Knowledgebase, Service, Github, CloudStorage, ImageGen, 3DTransform, BatchSplitter, IterationGate, PythonSandbox