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#
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
ETagis the revision. SendIf-None-Matchto get304 Not Modifiedwhen 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
revisionis 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=nas soon as revisionnis published, a URL no CDN edge has cached yet.
Structure#
{
"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#
schemaVersion1 | Format version. |
projectKey, environmentKeystring | Where it comes from. |
revisionnumber | 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. |
goalsGoalDef[] | 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#
enabledboolean | 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. |
offVariationkey | Served when the flag is off. |
defaultVariationkey? | Served when no rule matches; falls back to offVariation. |
overrides{ [userId]: key }? | Pinned users. |
rulesRule[] | In evaluation order. |
Rule#
keystring | Reported in decisions and exposures. |
type"rollout" | "experiment" | Only experiment rules log exposures. |
saltstring | Random, set once by the server. Part of the hash input. |
conditionsCondition? | Omitted = everyone. |
traffic0–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.