Bundle format

Server-side SDKs evaluate a versioned environment bundle locally. The format is public so you can inspect, archive, validate, or evaluate your configuration without depending on a proprietary runtime.

Version 1

{
  "fmt": 1,
  "envId": "env_01H...",
  "version": 42,
  "publishedAt": 1787539200000,
  "revoked": false,
  "segments": {},
  "flags": {
    "checkout-redesign": {
      "type": "boolean",
      "version": 7,
      "salt": "5f3a9c1d8e2b4a60",
      "on": true,
      "variants": [
        { "key": "off", "value": false },
        { "key": "on", "value": true }
      ],
      "offVariant": 0,
      "fallthrough": { "variant": 1 },
      "rules": []
    }
  }
}

Unknown fields are rejected. Consumers should validate the entire bundle before replacing the last known good version.

Top-level fields

Field	Type	Meaning
fmt	1	Bundle format version
envId	string	Environment identifier
version	positive integer	Monotonic environment publish version
publishedAt	non-negative integer	Publish time in Unix milliseconds
revoked	boolean	Whether the environment can be evaluated
segments	record	Segment definitions keyed by segment key
flags	record	Compiled flags keyed by flag key

A revoked bundle contains no flags.

Compiled flags

Each flag includes:

• type: boolean, string, or json
• a positive flag version
• a stable 16-character hexadecimal salt
• on state
• one or more unique variants
• an offVariant index
• fallthrough behavior
• ordered targeting rules

Boolean and string variant values must match their declared flag type. JSON variants can contain JSON-compatible values with finite numbers.

Serve behavior

A rule or fallthrough serves either one variant:

{ "variant": 1 }

or a rollout:

{
  "rollout": {
    "variations": [
      { "variant": 0, "weight": 50000 },
      { "variant": 1, "weight": 50000 }
    ]
  }
}

Rollout weights use 100,000 basis points and must total exactly 100000.

Fetch and cache safely

GET /v1/bundle
Authorization: Bearer sk_live_...
If-None-Match: "previous-etag"

The edge returns ETag and Cache-Control: private, no-cache. Keep the last validated bundle, send its ETag during refresh, and retain it on 304. Never activate a partially parsed or invalid bundle.

The official Node.js SDK implements validation, ETag polling, warm caching, streaming version notifications, and deterministic local evaluation.

Compatibility

Treat fmt as the compatibility boundary. A consumer that does not support the received format must reject it and continue with its last valid state or application defaults. Existing format-1 fields and evaluation vectors are append-only compatibility contracts.

Next: targeting reference or REST API.