Workflow Versioning

Every significant change to a workflow graph can be preserved as a named snapshot. Snapshots let you roll back to any earlier state, compare two versions side-by-side, and maintain a clear audit trail of what changed and when.

---

How versions are created

Trigger	What happens
Publish	A snapshot is created automatically before the workflow goes live
Manual snapshot	Click Snapshot in the Versions panel at any time while editing

Both methods produce a full copy of the workflow graph (nodes + edges + config) at that moment in time.

---

Versions panel

Open the Versions panel from the right action bar in the editor (clock icon). It shows a timeline of all snapshots for the current workflow:

─────────────────────────────────────────
  v7  Published  2026-06-20 14:32   [you]
  v6  Manual     2026-06-19 11:05   [alice]
  v5  Published  2026-06-15 09:41   [bob]
  v4  Manual     2026-06-14 16:20   [you]
  ...
─────────────────────────────────────────

Each entry shows:

• Version number — auto-incrementing integer
• Type — Published (triggered by publish action) or Manual (triggered by user)
• Timestamp — when the snapshot was taken
• Author — who took the snapshot

---

Rollback

To restore a previous version:

1. Open the Versions panel.
2. Click the version you want to restore.
3. Click Restore this version.

The workflow graph is replaced with the snapshot's graph. The current graph is automatically saved as a new Manual snapshot before the rollback, so you can undo the rollback if needed.

Rollback and status

Restoring a version sets the workflow back to Draft status, even if the current version is Published. You will need to go through the review and publish lifecycle again to make the restored version live.

---

Graph diff

To compare two versions:

1. Open the Versions panel.
2. Select a base version (click once to highlight).
3. Hold Shift and select a second version.
4. Click Compare.

The diff view highlights:

Highlight	Meaning
Green node / edge	Added in the newer version
Red node / edge	Removed in the newer version
Yellow node	Config changed between versions
No highlight	Unchanged

Click any highlighted node in the diff view to see a side-by-side comparison of its config fields.

---

Automatic snapshot on publish

When a reviewer clicks Approve & Publish on a staged workflow, the system:

1. Creates a Published snapshot of the current graph.
2. Updates the workflow's live version pointer to this snapshot.
3. Marks the workflow status as Published.

This means the production version is always tied to a specific snapshot. If you later edit and republish, a new snapshot is created and the live pointer moves forward — but the old snapshot remains in the timeline.

---

Storage and limits

• Snapshots store the full graph JSON (nodes, edges, and configs).
• There is no hard limit on the number of snapshots per workflow.
• Snapshots are retained indefinitely unless the workflow is deleted.
• Deleting a workflow deletes all its snapshots permanently.

---

API access

Version snapshots are accessible via the REST API for programmatic integrations:

GET  /api/v1/agent-workflows/{id}/versions
GET  /api/v1/agent-workflows/{id}/versions/{version_id}
POST /api/v1/agent-workflows/{id}/snapshot                  # create manual snapshot
GET  /api/v1/agent-workflows/{id}/versions/{a}/diff/{b}     # compare two versions
POST /api/v1/agent-workflows/{id}/rollback                  # body: {"version_id": "...", "notes": "..."}

See the API Reference for request/response schemas.