Sync API

The Sync API allows efficient synchronization of feature flag states to your application.

How Sync Works

The Flagstack gem automatically syncs feature flags in the background. You don't need to call this API directly — the gem handles it for you.

1. Your app starts and performs an initial sync
2. Flag states are cached locally (in-memory or database)
3. Background process polls for changes periodically
4. Changes propagate within seconds

Sync Endpoint

For custom integrations, you can call the sync endpoint directly:

GET /api/v1/sync

Example Request

$ curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     https://flagstack.io/api/v1/sync

Example Response

{
  "version": 1703097600,
  "features": {
    "new_checkout": {
      "boolean": true,
      "actors": [],
      "groups": [],
      "percentage_of_actors": 0,
      "percentage_of_time": 0
    },
    "beta_feature": {
      "boolean": false,
      "actors": ["User;123", "User;456"],
      "groups": ["beta_testers"],
      "percentage_of_actors": 25,
      "percentage_of_time": 0
    }
  }
}

Version Tracking

The version field is a Unix timestamp of the last change. Use it to check if your cache is stale:

$ curl -H "Authorization: Bearer YOUR_API_TOKEN" \
     -H "If-None-Match: 1703097600" \
     https://flagstack.io/api/v1/sync

# Returns 304 Not Modified if no changes since that version

Sync Interval

By default, the gem syncs every 10 seconds. Configure this in your initializer:

Flagstack.configure do |config|
  config.token = ENV["FLAGSTACK_TOKEN"]
  config.sync_interval = 30 # sync every 30 seconds (minimum: 10)
end

You can also force a manual sync at any time:

Flagstack.sync