apply_workflow_mutations
Submit ordered mutation commands to modify a workflow draft: add or remove steps, connect edges, and set conditions. Returns a summary of applied changes.
Instructions
Apply structural mutation commands to a workflow draft (add/remove steps, connect edges, set conditions). Read the workflow first for its version. Commands are applied IN ORDER, one backend call each, with the version threaded automatically — pass the version you read, not one per command.
RESPONSE IS A SUMMARY, not the document: version, appliedCount, launchable, validationIssues, stepCount, edgeCount. A real workflow document can exceed the response limit, which would turn a call that SUCCEEDED into an error you must not retry. Pass returnDocument: true, or call read_workflow, when you need the document itself.
Not transactional: if command N fails, commands before it stay applied and the error reports how many landed and which index failed — resume from there, do NOT replay the list. On a 409 conflict, re-read and retry.
Each command is { "type": "add_step", "payload": { … } }; the flat form { "type": "add_step", … } is accepted too. Valid types: update_workflow, add_trigger, update_trigger, remove_trigger, update_trigger_operator, group_triggers, ungroup_triggers, move_trigger, add_step, add_loop, update_step, remove_step, move_step, add_edge, update_edge, remove_edge, add_decision_condition, convert_to_loop, setup_loop_decision, advanced_edit, attach_output_schema, detach_output_schema.
PAYLOAD CONTRACT:
add_step builds a COMPLETE step in ONE call: { name, position: {after|before: , …} } are required, and id, type, typeId, config, contract, inputs, outputs and edgeType are all accepted alongside them. No follow-up update_step is needed merely to fill the step in.
add_edge accepts the document's own from/to as well as fromStepId/toStepId, and HONOURS an id you supply rather than replacing it, so ids stay diffable against an environment you are reproducing.
Payloads are STRICT: an unknown or misspelled key is a 422 that names it, never a silent drop. Read the error instead of assuming a value landed.
TWO INVARIANTS RUN AFTER EVERY EDIT, and the response reports what they did in systemAdjustments (addedEdges / removedEdges / rederivedInputs):
Every step is guaranteed to reach the END point; the platform wires that edge itself. An edge you did not ask for is this, and it is listed.
A bound input's contract, its description included, is DERIVED from the output it reads and cannot be authored on its own. Set the text on the PRODUCING step's output; a downstream description changing by itself is this rule at work, and the inputs it re-derived are listed.
Input Schema
| Name | Required | Description | Default |
|---|---|---|---|
| id | Yes | The workflow's id. | |
| mutations | Yes | Mutation commands to apply in order, each a JSON object with a `type` and its arguments (camelCase), either nested under `payload` or inline. | |
| returnDocument | No | Include the full workflow document in the response. Defaults to false — a real document can exceed the response limit and turn a successful call into an error. Prefer read_workflow when you need it. | |
| expectedVersion | Yes | The version you last read. Only the FIRST command uses it; later commands use the version returned by the previous one. |