Skip to main content
Four ideas, and the relationship between them is the whole model:

​
Why versions matter

Your code calls a deployment, not a workflow. Editing your graph in ComfyUI changes nothing about what your API calls do until you deploy the new version. That’s the safety property worth internalizing:
  • Experiment freely — production keeps running the deployed version
  • Ship deliberately — deploying is the moment behavior changes
  • Roll back by pointing at the previous version
The corollary catches people out: saving your workflow does not update your API. If a fix isn’t showing up in runs, check that you deployed it.

​
Inputs are a contract

Your graph’s input nodes define what callers must send. The inputs object in a run request maps to those names:
Renaming or removing an input node is a breaking change for every caller. Treat input names as a public API:
  • Adding an optional input is safe
  • Renaming one breaks existing callers
  • Removing one breaks existing callers
  • Changing the type breaks them quietly, which is worse
Need to change inputs incompatibly? Deploy it as a new deployment and migrate callers over, rather than mutating the one in production.

​
Inspecting a version

GET /workflow-version/{version_id} returns a version’s detail — useful when a run behaved unexpectedly and you want to confirm which revision actually executed. Every run records its workflow_version_id, so you can always trace a result back to the exact graph that produced it.

​
Machines

Runs execute on a machine, recorded as machine_id on the run. Two runs of the same deployment on different machines should behave identically — if they don’t, the machine is where to look, and the machine_id is what to report.

​
Run origin

Every run records where it came from: Useful for separating your own testing from real traffic when you’re reviewing history.

​
Practical workflow

1

Build and test by hand

Get the graph right in ComfyUI first. Debugging a graph through API calls is slow.
2

Name your inputs deliberately

They’re a contract. input_image beats image2.
3

Deploy

Note the deployment_id. That’s what your code stores.
4

Call it once by hand

Confirm one run end to end before wiring it into anything.
5

Version forward

For breaking changes, deploy alongside and migrate — don’t mutate what’s live.