Editing Flows

Audience: Everyone / Developers · Tags: flow, edit, version, draft

Purpose. Change what a flow does — its trigger, its actions, or the details inside them — without losing the history of what it used to do.

When to use. Any time your automation's requirements change: a different Slack channel, an extra action, a corrected field.

How versioning works

A flow's live behavior is defined by its active version — an immutable snapshot created the moment a draft is promoted. You never edit a version directly. Instead:

1. You create (or reuse) a draft — a mutable working copy of the definition.
2. You edit the draft's JSON until it's right.
3. You promote the draft. SnapLink snapshots it as a new, immutable FlowVersion (version number = previous max + 1) and the flow's activeVersionId moves to point at it.

The old version is never deleted or changed — it stays visible forever in GET /flows/:id/versions. Every run is pinned to the exact version it used (flowVersionId), so historical runs stay accurate even after you edit the flow again. A draft can only be edited or promoted while its status is "proposed"; once promoted it becomes "accepted" and is locked — to make further changes you create a new draft.

Prerequisites

• An existing flow (flowId) — see Creating Flows if you don't have one yet.
• Authorization: Bearer $TOKEN on every request below.

Step-by-step (API)

1. Start a draft

If you don't already have an open (proposed) draft on this flow, create one from the flow's current definition — or from scratch:

curl -X POST https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flows/flow_1a2b3c4d5e6f/drafts \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "trigger": { "key": "trigger", "connectorKey": "webhook", "triggerType": "webhook" },
      "actions": [
        { "key": "notify", "connectorKey": "slack", "actionType": "send_message",
          "input": { "channel": "C0000000", "text": "New lead received" } }
      ]
    }
  }'

This returns a FlowDraft with an id (draft_...) and status: "proposed".

2. Edit the draft

Keep refining the same draft with PUT /drafts/:id — each call replaces the draft's definition (SnapLink structurally re-validates it every time):

curl -X PUT https://api.snaplink.cloudsolutionaccelerators.com/api/v1/drafts/draft_9f8e7d6c5b4a \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "definition": {
      "trigger": { "key": "trigger", "connectorKey": "webhook", "triggerType": "webhook" },
      "actions": [
        { "key": "notify", "connectorKey": "slack", "actionType": "send_message",
          "input": { "channel": "C1111111", "text": "New lead received — updated channel" } },
        { "key": "log", "connectorKey": "rest_sdk", "actionType": "request",
          "input": { "url": "https://api.example.com/log", "method": "POST" } }
      ]
    }
  }'

Response: the same draft, updatedAt bumped. Run validate as many times as you like against the draft's definition before you commit to it.

3. Promote when you're happy with it

curl -X POST https://api.snaplink.cloudsolutionaccelerators.com/api/v1/drafts/draft_9f8e7d6c5b4a/promote \
  -H "Authorization: Bearer $TOKEN"

{ "ok": true, "data": {
  "flow": { "id": "flow_1a2b3c4d5e6f", "status": "active", "activeVersionId": "ver_00002", "...": "..." },
  "version": { "id": "ver_00002", "flowId": "flow_1a2b3c4d5e6f", "versionNumber": 2, "definition": { "...": "..." }, "checksum": "sha256...", "createdAt": "2026-07-02T14:10:00.000Z" }
} }

The flow now runs the new definition on its next trigger. The prior version (1) is still there:

curl https://api.snaplink.cloudsolutionaccelerators.com/api/v1/flows/flow_1a2b3c4d5e6f/versions \
  -H "Authorization: Bearer $TOKEN"

{ "ok": true, "data": { "versions": [
  { "id": "ver_00001", "versionNumber": 1, "...": "..." },
  { "id": "ver_00002", "versionNumber": 2, "...": "..." }
] } }

Best practices

• Validate the draft before promoting — a bad promote is still fully reversible (just promote another corrected draft), but skipping validation wastes a round trip.
• Treat "promote" as the same trust boundary as "activate" — nothing in a draft affects running flows until you promote it.
• If you're editing via Snap Studio instead of the raw API, the same rules apply underneath: Studio's approve step creates and promotes a draft for you in one action. See Snap Studio.

FAQ

Can I go back to an old version? There's no one-click rollback endpoint today — copy the old version's definition from GET /flows/:id/versions into a new draft and promote that. Do old runs change when I promote a new version? No — each run records the exact flowVersionId it used, permanently. What happens to an unpromoted draft I abandon? It just sits as proposed and has no effect; nothing runs from a draft until it's promoted.

If something goes wrong

If the flow doesn't pick up your edits, confirm you actually promoted the new draft (not just saved it) — see Flow not running.

---

Related: Creating Flows · Flow Validation · Managing Flows