Process Versioning

Every process definition and decision definition in Stateway is versioned. This guide explains how versioning works, when to create new versions, and how to roll back.

How Versioning Works

When you create a definition with POST /v1/definitions, it is stored as version 1. Every subsequent PUT /v1/definitions/:key creates a new version with an incremented number.

• Only one version of a given key can be active at a time
• GET /definitions/:key always returns the active version
• GET /definitions/:key/versions returns the full history
• Instances are permanently bound to the definition_id they were started with — they do not upgrade automatically when a new version becomes active

The same rules apply to decision definitions (/decisions/:key).

Creating a New Version

curl -X PUT https://api.stateway.io/v1/definitions/expense-approval \
  -H "X-API-Key: sw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Expense Approval v2",
    "source_type": "json",
    "source": { ... }
  }'

{
  "data": {
    "id": "def_02k...",
    "key": "expense-approval",
    "version": 2,
    "is_active": true,
    "created_at": "2026-05-01T09:00:00.000Z"
  }
}

After this call:

• Version 2 is active
• Version 1 is inactive but accessible via GET /definitions/expense-approval/versions/1
• Any new POST /instances with definition_key: expense-approval will use version 2
• Instances already running on version 1 continue on version 1

Inspecting Version History

curl https://api.stateway.io/v1/definitions/expense-approval/versions \
  -H "X-API-Key: sw_live_your_key"

{
  "data": [
    { "id": "def_01j...", "version": 1, "is_active": false, "created_at": "2026-04-26T12:00:00.000Z" },
    { "id": "def_02k...", "version": 2, "is_active": true,  "created_at": "2026-05-01T09:00:00.000Z" }
  ]
}

Get a Specific Version

curl https://api.stateway.io/v1/definitions/expense-approval/versions/1 \
  -H "X-API-Key: sw_live_your_key"

Rolling Back

Rollback atomically reactivates a previous version and deactivates the current one:

curl -X POST https://api.stateway.io/v1/definitions/expense-approval/rollback \
  -H "X-API-Key: sw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "version": 1 }'

{
  "data": {
    "key": "expense-approval",
    "version": 1,
    "is_active": true,
    "updated_at": "2026-05-10T08:00:00.000Z"
  }
}

After rollback:

• Version 1 is active; version 2 is inactive
• New instances use version 1
• Existing instances on version 2 continue running on version 2

Version numbering after rollback

If you create a new version after rolling back from version 2 to version 1, the new version will be assigned number 3 (not 2, which already exists). The engine uses MAX(version) + 1 to avoid collisions:

v1 → v2 → rollback to v1 → v3 (next PUT)

Decision Rollback

The same rollback mechanism applies to decision definitions:

curl -X POST https://api.stateway.io/v1/decisions/discount-calculator/rollback \
  -H "X-API-Key: sw_live_your_key" \
  -H "Content-Type: application/json" \
  -d '{ "version": 1 }'

Rollback vs. Creating a New Version

Situation	Recommended action
You published a broken version	Rollback — faster than rewriting, preserves history
You want to improve the process	New version via PUT — keeps a clean forward history
You need to compare versions	Use GET /versions/:v to inspect either version
An instance is stuck in an older version	Instances cannot be migrated between versions — resolve via variable update or terminate + restart

source_hash for Audit

Every definition version has a source_hash — a SHA-256 digest of the original source content. It is returned in every GET, POST, and PUT response.

{
  "data": {
    "version": 2,
    "source_hash": "a3f8c2d1e9b7f64..."
  }
}

For process instances, the definition_hash at startup is stored with the instance record. This enables you to verify that an instance ran on a specific — unmodified — version of the definition even if that version has since been updated.

Best Practices

• Test a new version before publishing — evaluate the definition in a staging environment before using it in production
• Keep versions numbered sequentially — avoid rollback churn that creates gaps in version history
• Never delete a version that has running instances — soft-delete marks the definition inactive but does not remove the definition_id that instances reference
• Document what changed — use the name or description field to note what changed between versions; the API does not have a changelog field, so add this context in your deployment tooling