LiftCanary

API

Datafile format

The JSON every SDK downloads and decides from.

The datafile is the complete, self-contained description of one environment: every flag with its rules, plus the audiences, locations, redirect tests and auto-tracked goals they need. SDKs make every decision from it, locally. You only need this page to build an SDK, debug a decision or cache datafiles yourself.

Fetching it#

Terminal
curl https://cdn.liftcanary.com/datafiles/pk_xxxxxxxx.json
  • Public: the SDK key in the path is all that's needed. It contains no secrets and no personal data.
  • The ETag is the revision. Send If-None-Match to get 304 Not Modified when nothing changed; SDKs poll this way.
  • Cache-Control: public, max-age=10, s-maxage=10, stale-while-revalidate=60: a change reaches every CDN edge within about 10 seconds.
  • SDKs ignore a datafile whose revision is lower than the one they have, so a stale CDN edge can never roll a user back.
  • Server SDKs also listen to /stream/pk_… (server-sent events) and download ?rev=n as soon as revision n is published, a URL no CDN edge has cached yet.

Structure#

pk_….json
{
  "schemaVersion": 1,
  "projectKey": "web",
  "environmentKey": "production",
  "revision": 42,
  "segments": {
    "mobile_tr": { "key": "mobile_tr", "conditions": { "all": [
      { "attribute": "country", "op": "eq", "value": "TR" },
      { "attribute": "device", "op": "eq", "value": "mobile" }
    ] } }
  },
  "locations": {
    "product_pages": {
      "key": "product_pages",
      "include": [{ "type": "startsWith", "value": "/products/", "caseSensitive": false }],
      "exclude": [{ "type": "contains", "value": "preview=1", "caseSensitive": false }]
    }
  },
  "flags": {
    "new_checkout": {
      "key": "new_checkout",
      "enabled": true,
      "variables": { "button_text": { "type": "string", "defaultValue": "Buy now" } },
      "variations": {
        "off": { "key": "off", "enabled": false },
        "control": { "key": "control", "enabled": true },
        "one_page": { "key": "one_page", "enabled": true, "variables": { "button_text": "Complete order" } }
      },
      "offVariation": "off",
      "overrides": { "qa_user_1": "one_page" },
      "rules": [
        {
          "key": "checkout_test",
          "type": "experiment",
          "salt": "k3J9x2Lq",
          "conditions": { "segment": "mobile_tr" },
          "traffic": 5000,
          "allocation": [{ "variation": "control", "weight": 5000 }, { "variation": "one_page", "weight": 5000 }]
        }
      ]
    }
  },
  "redirects": {},
  "goals": [
    { "key": "add_to_cart", "eventKey": "add_to_cart", "trigger": { "kind": "click", "selector": "button.add-to-cart" } }
  ]
}

Top level#

schemaVersion
1
Format version.
projectKey, environmentKey
string
Where it comes from.
revision
number
Increases with every change in the environment.
segments
{ [key]: { key, conditions } }
Audiences used by rules.
locations
{ [key]: LocationDef }
Saved locations: include, exclude?, trigger?. Present only when the project has locations.
flags
{ [key]: Flag }
Every non-archived flag.
redirects
{ [flagKey]: RedirectDef }
Redirect tests: pages, the variable holding the destination, and query/hash handling.
changes
{ [flagKey]: PageChangesDef }
No-code tests, A/A tests and deploys: the pages (and saved location) where the snippet applies each variation's visual, css and js variables.
goals
GoalDef[]
Goals the website snippet tracks by itself (everything except code and billing goals).
integrations
{ ga4?, gtm?, segment?, mixpanel?: { eventName, firstOnly?, waitForPageView? }, names?, chargebee?: { field }, paddle?: { field }, stripe?: { field } }
Analytics tools the website snippet reports exposures to, and experiment/variation names by flag key when the project shares them. See Integrations. chargebee, paddle, stripe: the environment is connected to that billing system, and the snippet (with checkout.js, which it loads then) passes the visitor's id to its checkouts: Chargebee's customer field, this key of Paddle's custom data, or Stripe's client_reference_id (see Chargebee, Paddle, Stripe).
consentBanner
{ position?, theme?, buttonColor?, radius?, siteFont?, reopenButton?, privacyUrl?, text? }
How LiftCanary's consent banner looks, once the project has designed it. See Consent.

Flag#

enabled
boolean
The environment's on/off switch.
variables
{ [name]: { type, defaultValue } }
type: boolean, string, number, json.
variations
{ [key]: { key, enabled, variables? } }
Display names and order are not published.
offVariation
key
Served when the flag is off.
defaultVariation
key?
Served when no rule matches; falls back to offVariation.
overrides
{ [userId]: key }?
Pinned users.
rules
Rule[]
In evaluation order.

Rule#

key
string
Reported in decisions and exposures.
type
"rollout" | "experiment"
Only experiment rules log exposures.
salt
string
Random, set once by the server. Part of the hash input.
conditions
Condition?
Omitted = everyone.
traffic
0–10000
Share of matching users the rule takes.
allocation
[{ variation, weight }]
Weights in buckets, summing to 10000.

How these are evaluated, step by step, is in How decisions are made. Datafiles of past revisions are available from the management API: GET /v1/projects/:project/environments/:env/datafile?revision=n.