Track every flag change with automatic snapshots, view history, and roll back to any previous version

Flag Versioning & History

Flaggr automatically creates a version snapshot every time a flag is modified. You can view the full history of changes and roll back to any previous version.

How Versioning Works

Every flag mutation (create, update, toggle, rollback) creates a new version entry containing:

A full snapshot of the flag at that point in time
Who made the change (user ID, email, name)
What changed (change type and summary)
When the change was made (timestamp)
An auto-incrementing version number

Version 1: created (alice@example.com)
    ↓
Version 2: updated — added targeting rule (alice@example.com)
    ↓
Version 3: toggled — enabled (bob@example.com)
    ↓
Version 4: updated — changed rollout to 50% (alice@example.com)
    ↓
Version 5: rollback — rolled back to version 2 (bob@example.com)

Versioning is automatic — you don't need to enable it or configure anything. Every flag change is tracked.

Viewing History

Get Version History

Retrieve the version history for a flag:

curl -s "/api/flags/checkout-v2/history?serviceId=svc-web&environment=production" \
  -H "Authorization: Bearer flg_your_token"

Response Format

{
  "versions": [
    {
      "id": "ver-abc123",
      "flagKey": "checkout-v2",
      "serviceId": "svc-web",
      "environment": "production",
      "projectId": "proj-123",
      "version": 4,
      "snapshot": {
        "key": "checkout-v2",
        "name": "Checkout V2",
        "type": "boolean",
        "enabled": true,
        "defaultValue": false,
        "targeting": [
          {
            "id": "rule-1",
            "conditions": [{ "property": "plan", "operator": "equals", "value": "enterprise" }],
            "rolloutPercentage": 50
          }
        ]
      },
      "changedBy": "user-456",
      "changedByEmail": "alice@example.com",
      "changedByName": "Alice",
      "changeType": "update",
      "changeSummary": "Changed rollout percentage to 50%",
      "timestamp": "2026-02-21T10:30:00.000Z",
      "timestampMs": 1771585800000
    }
  ],
  "total": 4,
  "limit": 50,
  "offset": 0,
  "hasMore": false
}

Query Parameters

Parameter	Type	Default	Description
`serviceId`	string	required	Service the flag belongs to
`environment`	string	`development`	Environment to query
`limit`	number	`50`	Max versions to return (capped at 100)
`offset`	number	`0`	Pagination offset

Version Entry Fields

Field	Type	Description
`id`	string	Unique version identifier
`flagKey`	string	Flag key
`serviceId`	string	Service ID
`environment`	string	Environment
`projectId`	string	Project ID
`version`	number	Auto-incrementing version number
`snapshot`	object	Full flag state at this version
`changedBy`	string	User ID who made the change
`changedByEmail`	string	User's email
`changedByName`	string	User's display name
`changeType`	string	`create`, `update`, `toggle`, or `rollback`
`changeSummary`	string	Human-readable description of the change
`timestamp`	string	ISO 8601 timestamp
`timestampMs`	number	Unix timestamp in milliseconds

Rolling Back

Roll Back to a Specific Version

Restore a flag to the exact state it was in at a previous version:

curl -X POST "/api/flags/checkout-v2/rollback/2?serviceId=svc-web&environment=production" \
  -H "Authorization: Bearer flg_your_token"

Response

{
  "flag": {
    "key": "checkout-v2",
    "name": "Checkout V2",
    "type": "boolean",
    "enabled": false,
    "defaultValue": false,
    "targeting": [
      {
        "id": "rule-1",
        "conditions": [{ "property": "plan", "operator": "equals", "value": "enterprise" }],
        "rolloutPercentage": 100
      }
    ]
  },
  "rolledBackToVersion": 2
}

What Rollback Does

When you roll back to version N:

Retrieves the full flag snapshot from version N
Restores all flag properties: name, description, type, enabled, default value, tags, variants, targeting rules, and public status
Creates a new version (N+1) with changeType: "rollback" and a summary like "Rolled back to version 2"
Invalidates caches for the affected service and flag
Publishes a flag update event for real-time subscribers
Logs an audit event with the rollback details

Info

Rollback creates a new version rather than deleting history. The version timeline is append-only, so you always have a complete audit trail.

Rollback Requirements

Requirement	Details
Authentication	Valid API token or session
Authorization	`write` permission on the project
Version	Must be a valid, existing version number (>= 1)
Flag	The flag must exist in the specified service + environment

Audit Trail Integration

Version history integrates with audit logging. Every version change is also recorded in the audit log with:

User identity (who performed the action)
IP address and user agent
Before and after state comparison
Timestamp

This gives you two complementary views:

Version history — flag-specific, with full snapshots for rollback
Audit log — project-wide, with cross-entity activity tracking

Use Cases

Debugging Unexpected Behavior

When a flag isn't behaving as expected, check the history to see recent changes:

# Get the last 5 versions
curl -s "/api/flags/checkout-v2/history?serviceId=svc-web&environment=production&limit=5" \
  -H "Authorization: Bearer flg_your_token" | jq '.versions[] | {version, changeType, changedByEmail, timestamp}'

Comparing Versions

Fetch two version snapshots and diff them to see exactly what changed:

# Get full history and compare versions
curl -s "/api/flags/checkout-v2/history?serviceId=svc-web&environment=production" \
  -H "Authorization: Bearer flg_your_token" | \
  jq '[.versions[] | select(.version == 2 or .version == 4)] | {before: .[1].snapshot, after: .[0].snapshot}'

Emergency Rollback

If a flag change causes an incident, roll back immediately:

# 1. Check recent history to find the last known good version
curl -s "/api/flags/checkout-v2/history?serviceId=svc-web&environment=production&limit=5" \
  -H "Authorization: Bearer flg_your_token"
 
# 2. Roll back to the last good version
curl -X POST "/api/flags/checkout-v2/rollback/3?serviceId=svc-web&environment=production" \
  -H "Authorization: Bearer flg_your_token"