LiftCanary

API

Endpoint reference

Every endpoint, with its request body.

All management endpoints need Authorization: Bearer sk_… (see API overview). :project, :flag and the other path parameters are keys.

Projects and environments#

GET/v1/projectsList projects#
POST/v1/projectsCreate a project#

Body

keyrequired
key
Project key.
namerequired
string
Display name.
environments
[{ key, name }]
1–20 environments. Default: development and production.
GET/v1/projects/:projectA project with its environments, SDK keys and current revisions#
GET/v1/projects/:project/integrationsAnalytics integrations#

Every tool (ga4, gtm, segment, mixpanel) with enabled, eventName, defaultEventName, and sendNames.

PUT/v1/projects/:project/integrationsChange analytics integrations#

Admins. { ga4?: { enabled, eventName }, …, sendNames? }; publishes. See Integrations.

GET/v1/projects/:project/webhooks/:providerBilling webhooks#

:provider is chargebee, paddle or stripe. Every environment with its source (id, path, field, secret: set, or for Paddle and Stripe missing until their signing secret is pasted in and unreadable after INTERNAL_TOKEN changed; createdAt, rotatedAt) or null, and for connected ones health over the last 7 days (events, withId, inExperiments, lastEventAt; null without analytics), plus auth (password or signature), username (Chargebee), the events to send and dataPlaneUrl (hybrid). See Chargebee, Paddle and Stripe.

POST/v1/projects/:project/environments/:env/webhooks/:providerConnect a billing system#

Admins. Chargebee: answers the source with password, shown only here, and connecting again replaces it. Paddle, Stripe: connecting again changes only what the body says. Connecting needs a plan with integrations; replacing a password or key doesn't. Connecting, disconnecting and changing the field publish the environment (integrations.chargebee, integrations.paddle).

Body

field
string
Where the visitor's id travels: Chargebee's customer custom field (default cf_liftcanary_id), the key of Paddle's custom data or of Stripe's metadata (default liftcanary_id).
secret
string
Paddle and Stripe: the signing secret (pdl_ntfset_…, whsec_…). It can also come later with PATCH.
PATCH/v1/projects/:project/environments/:env/webhooks/:providerChange the field, or the signing secret#

Admins.

Body

field
string
Chargebee: an API name, cf_ and lowercase letters, digits or _. Paddle, Stripe: letters, digits or _, not starting with a digit (Stripe: up to 40).
secret
string
Paddle and Stripe: the signing secret, kept encrypted and never returned.
DELETE/v1/projects/:project/environments/:env/webhooks/:providerDisconnect a billing system#

Admins. The provider's calls are refused from then on.

The design of LiftCanary's consent banner; {} while it's LiftCanary's default.

Admins. The whole design: { position?, theme?, buttonColor?, radius?, siteFont?, reopenButton?, privacyUrl?, text?: { [lang]: { title?, text?, accept?, reject?, policy? } } }; defaults and empty fields are dropped. Publishes. See Consent.

PATCH/v1/projects/:projectRename a project#

Body

namerequired
string
Display name. The key can't change.
DELETE/v1/projects/:projectDelete a project (admin)#

Deletes its environments, flags, audiences, locations, goals, experiments and collected events, and its SDK keys stop working.

GET/v1/projects/:project/visitors/:idWhat's stored about a visitor (anonymous id or user id, with linked ids): { ids, exposures, events, firstSeen, lastSeen } (admin)#
DELETE/v1/projects/:project/visitors/:idDelete a visitor's exposures, events and identity links in every environment of the project (admin)#

Recorded in the audit log without the ids.

POST/v1/projects/:project/environmentsAdd an environment#

Existing flags start switched off in the new environment.

Body

keyrequired
key
Environment key.
namerequired
string
Display name.
PATCH/v1/projects/:project/environments/:envRename an environment#

Body

namerequired
string
Display name. The key and SDK key stay the same.
POST/v1/projects/:project/environments/:env/sdk-keyRegenerate the SDK key (admin)#

The old key stops serving the datafile at once; the collector drops its events within about a minute.

DELETE/v1/projects/:project/environments/:envDelete an environment (admin)#

A project keeps at least one environment.

GET/v1/projects/:project/environments/:env/datafileThe current datafile#

Add ?revision=n for a past one.

GET/v1/projects/:project/environments/:env/datafilesRevision history (latest 100)#
GET/v1/projects/:project/environments/:env/activityWhen events last arrived (install check)#

Flags#

GET/v1/projects/:project/flagsList flags with their kind and per-environment on/off state#
POST/v1/projects/:project/flagsCreate a flag#

Body

keyrequired
key
Flag key.
namerequired
string
Display name.
description
string
Up to 2,000 characters.
variables
[{ key, type, defaultValue }]
type: boolean, string, number or json. Up to 100.
variations
[{ key, name?, enabled, variables? }]
1–20. Default: off (disabled) and on (enabled). variables overrides the defaults.
redirect
object
Redirect test settings (normally created through experiments).
changes
{ location?, include, exclude }
Pages of a no-code test; needs css and js text variables (and optionally a visual JSON variable) (normally created through experiments).
Example
{
  "key": "new_checkout",
  "name": "New checkout",
  "variables": [{ "key": "button_text", "type": "string", "defaultValue": "Buy now" }],
  "variations": [
    { "key": "off", "enabled": false },
    { "key": "control", "enabled": true },
    { "key": "one_page", "enabled": true, "variables": { "button_text": "Complete order" } }
  ]
}
GET/v1/projects/:project/flags/:flagA flag with its targeting in every environment (each with its version)#
PATCH/v1/projects/:project/flags/:flagChange name, description, variables or variations#

Only the fields you send change. Removing a variation that targeting still uses is refused. Send redirect: null to remove redirect settings.

DELETE/v1/projects/:project/flags/:flagArchive a flag#

It disappears from datafiles.

PUT/v1/projects/:project/flags/:flag/environments/:envReplace the targeting in one environment#

Send If-Match with the version you read; the response's ETag is the new version. See concurrency.

Body

enabledrequired
boolean
The on/off switch.
offVariationrequired
key
Served when off.
defaultVariation
key | null
Served when on and no rule matches. Default: the off variation.
overrides
{ [userId]: variation }
Pinned users.
rules
Rule[]
Up to 100, in order. Each: key, type (rollout | experiment), conditions?, traffic (0–10000), allocation (weights summing to 10000).
Example
{
  "enabled": true,
  "offVariation": "off",
  "overrides": { "qa_user_1": "one_page" },
  "rules": [
    {
      "key": "checkout_test",
      "type": "experiment",
      "conditions": { "attribute": "country", "op": "in", "value": ["TR", "DE"] },
      "traffic": 5000,
      "allocation": [{ "variation": "control", "weight": 5000 }, { "variation": "one_page", "weight": 5000 }]
    }
  ]
}
POST/v1/projects/:project/flags/:flag/environments/:env/toggleKill switch#

Body

enabledrequired
boolean
On or off; rules are kept.
POST/v1/projects/:project/flags/:flag/variations/:variation/renameRename a variation key everywhere#

Refused with 409 variation_in_running_experiment while the variation is in a running experiment.

Body

keyrequired
key
The new key.

Audiences (segments)#

The API calls audiences segments; conditions refer to them with { "segment": "key" }.

GET/v1/projects/:project/segmentsList audiences#
POST/v1/projects/:project/segmentsCreate an audience#

Body

keyrequired
key
Audience key.
namerequired
string
Display name.
conditionsrequired
Condition
A condition tree.
GET/v1/projects/:project/segments/:segmentAn audience#
PATCH/v1/projects/:project/segments/:segmentChange name or conditions#

Cycles between audiences are rejected.

DELETE/v1/projects/:project/segments/:segmentDelete an audience#

409 while a flag or another audience uses it.

Locations#

GET/v1/projects/:project/locationsList locations, each with where it's used#
POST/v1/projects/:project/locationsCreate a location#

Body

keyrequired
key
Location key.
namerequired
string
Display name.
description
string
Optional.
includerequired
UrlMatch[]
1–50 rules: { type, value, caseSensitive? }.
exclude
UrlMatch[]
Up to 50 rules.
trigger
Trigger | null
pageload (default), click/visible/element with a selector, or manual. See triggers.
GET/v1/projects/:project/locations/:locationA location with its usage#
PATCH/v1/projects/:project/locations/:locationChange a location#

Only the fields you send change. A trigger is refused while a redirect test uses the location.

DELETE/v1/projects/:project/locations/:locationDelete a location#

409 while anything uses it; the message lists what.

Goals#

GET/v1/projects/:project/goalsGoals with recent event counts and usage, plus tracked events without a goal#
POST/v1/projects/:project/goalsCreate a goal#

Body

keyrequired
key
Goal ID.
namerequired
string
Display name.
eventKeyrequired
string
Event it counts.
description
string
Optional.
type
"conversion" | "mean" | "ratio"
Default conversion.
direction
"increase" | "decrease"
Default increase.
trigger
GoalTrigger
Default { "kind": "code" }. See goal triggers.
lagDays
integer
Late conversions: days (0–30) its events keep counting after an experiment ends. Default 0. See Goals.
PATCH/v1/projects/:project/goals/:goalChange a goal#
DELETE/v1/projects/:project/goals/:goalDelete a goal#

Experiments#

GET/v1/projects/:project/experimentsList experiments#

?status=draft|running|stopped; ?summary=0 skips the headline results.

POST/v1/projects/:project/experimentsCreate an experiment#

Body: see Experiments; no-code and A/A tests: No-code tests.

POST/v1/projects/:project/deploysCreate a deploy (personalization)#

CSS/JS for an audience on some pages, on its own flag. See No-code tests.

POST/v1/projects/:project/flags/:flag/editor-sessionsOpen the visual editor#

Editor role; the flag must be a no-code test or personalization. Answers { token, expiresAt }: a link token valid for two hours. See Visual editor.

GET/v1/projects/:project/experiments/:idAn experiment#
PATCH/v1/projects/:project/experiments/:idChange an experiment#

Body

name
string
hypothesis
string
primaryMetric
metric | null
secondaryMetrics
metric[]
confidenceLevel
80 | 90 | 95 | 99
guardrails
guardrail[]
Clears a recorded guardrail alert.
guardrailAction
"alert" | "stop"
funnel
[{ eventKey }]
schedule
{ startAt?, stopAt? }
Start a draft and/or end the experiment by itself; null clears a time. See Schedule.
POST/v1/projects/:project/experiments/:id/startStart a draft#
POST/v1/projects/:project/experiments/:id/stopStop#

Body

ship
variation | null
Give everyone in the audience this variation from now on; null just ends the test.
POST/v1/projects/:project/experiments/:id/guardrails/checkCheck guardrails now#
GET/v1/projects/:project/experiments/:id/reportEvery goal, the funnel and guardrails#
GET/v1/projects/:project/experiments/:id/breakdownResults per segment#

?by=device (any attribute) and optionally ?metric=&type=; answers segments with each one's variations and comparisons. Without by: the attributes to choose from. See Breakdown by segment.

GET/v1/projects/:project/experiments/:id/resultsOne metric#

?metric=<eventKey>&type=conversion|mean|ratio; default: the primary metric.

GET/v1/projects/:project/flags/:flag/environments/:env/resultsResults of any experiment rule#

?metric=&type=, optional rule, control, from, to (ISO or milliseconds).

Websites#

GET/v1/projects/:project/environments/:env/websitesWebsites with status, plus discovered origins#
PUT/v1/projects/:project/environments/:env/websitesSet websites and mode#

Body

websites
string[]
Patterns: host, *.domain or host:port.
mode
"monitor" | "enforce"
enforce needs admin and at least one website.

Organization, team and tokens#

GET/v1/meThe current user, organization, role and other organizations#
POST/v1/me/organizationSwitch organization (sessions)#

Body

organizationIdrequired
uuid
PATCH/v1/meChange your name (sessions)#

Body

namerequired
string
1–100 characters.
POST/v1/me/termsAccept the current Terms of Service after they changed (sessions)#

Body

versionrequired
string
user.terms.currentVersion from GET /v1/me; 409 terms_changed if it's no longer current.
PUT/v1/me/marketingMarketing email on or off (sessions)#

Body

optInrequired
boolean
GET/v1/organization/data-planeHybrid deployment: whether it's enabled, the data plane address, whether a license key was issued (admins)#
PUT/v1/organization/data-planeSet or clear the data plane address (owners; hybrid only)#

Body

urlrequired
string | null
HTTPS address of your data plane; null disconnects.
POST/v1/organization/data-plane/license-keyIssue a new license key, returned once; the previous key stops working (owners; hybrid only)#
POST/v1/organization/data-plane/checkCheck that the data plane answers signed requests: { ok, error? } (admins)#
GET/v1/me/deletionWhat deleting your account would delete (erase), leave (leave) or block it (blocked: you're the only owner of a team) (sessions)#
DELETE/v1/meDelete your account for good (sessions); 409 sole_owner while blocked#

Body

passwordrequired
string
code
string
With two-step sign-in.
recoveryCode
string
Instead of code.
POST/v1/me/2fa/setupStart setting up two-step sign-in (sessions)#

Returns { secret, otpauthUri } for the authenticator app; not active until enabled.

POST/v1/me/2fa/enableTurn two-step sign-in on (sessions)#

Returns the 10 recovery codes, once. Needs a confirmed email address (409 email_unverified). Wrong passwords and codes in account settings are limited to 10 per 15 minutes.

Body

coderequired
string
The first code from the app.
passwordrequired
string
The account's password.
POST/v1/me/2fa/recovery-codesNew recovery codes (sessions)#

Body

coderequired
string
A current code.
POST/v1/me/2fa/disableTurn two-step sign-in off (sessions)#

Body

passwordrequired
string
code
string
recoveryCode
string
Instead of code.
POST/v1/me/email/verificationSend the confirmation email again (sessions)#

3 per hour; the earlier link stops working.

PATCH/v1/me/notificationsChoose notification emails (sessions)#

Body

guardrails
boolean
schedule
boolean
usage
boolean
POST/v1/me/passwordChange your password (sessions)#

Signs out every other session of yours, in every organization.

Body

currentPasswordrequired
string
newPasswordrequired
string
At least 10 characters.
GET/v1/me/sessionsYour active sessions (sessions)#

Each with current, organization, createdAt and lastUsedAt.

DELETE/v1/me/sessionsSign out every other session#
DELETE/v1/me/sessions/:idSign out one session#

Not the current one: use sign-out for that.

PATCH/v1/organizationRename the organization (admin)#

Body

namerequired
string
1–100 characters.
GET/v1/usageTested visitors this month#

Visitors who entered an experiment this calendar month (UTC): visitors, limit, share, status (ok | warning | over | blocked), projects, and on LiftCanary Cloud plan. See Plans and billing.

GET/v1/billingPlan, limits and subscription#

plan, testedVisitors, projects, seats, features, subscription (status, interval, currentPeriodEnd, cancelAtPeriodEnd) and current usage. plansEnforced: false on self-hosted installations.

POST/v1/billing/checkoutStart a subscription (admin)#

Returns the checkout url. The plan changes when the payment provider confirms it.

Body

planrequired
"starter" | "growth" | "scale"
interval
"monthly" | "annual"
Default monthly.
POST/v1/billing/changeChange plan or interval (admin)#

At once, prorated. 202: the plan updates when the payment provider confirms.

Body

planrequired
"starter" | "growth" | "scale"
interval
"monthly" | "annual"
POST/v1/billing/cancelCancel at the end of the period (admin)#

Then Free. POST /v1/billing/resume keeps the subscription. Nothing is deleted.

POST/v1/billing/portalInvoices and payment method (admin)#

Returns the url of the payment provider's customer portal.

GET/v1/membersMembers#
PATCH/v1/members/:userIdChange a role#

Body

rolerequired
"viewer" | "editor" | "admin" | "owner"
Up to your own role.
DELETE/v1/members/:userIdRemove a member#

The last owner can't be removed.

GET/v1/invitationsPending invitations#
POST/v1/invitationsInvite someone#

Returns a token for an invitation link, valid for 7 days, to send another way; the email has its own link. emailed: false when the organization (30 an hour) or the address (5 a day) has had too many invitation emails.

Body

emailrequired
string
rolerequired
role
DELETE/v1/invitations/:idCancel an invitation#
GET/v1/api-tokensAPI tokens (without secrets)#
POST/v1/api-tokensCreate an API token#

The secret is in the response, once.

Body

namerequired
string
rolerequired
"viewer" | "editor" | "admin"
DELETE/v1/api-tokens/:idRevoke a token#
GET/v1/audit-logAudit log#

?project=<key>, ?limit= (1–200, default 50).

Sign-in (dashboard sessions)#

Used by the dashboard. Sessions are an alternative to API tokens for interactive use.

POST/auth/signupCreate an account and organization#

Body

emailrequired
string
passwordrequired
string
At least 10 characters.
namerequired
string
organizationNamerequired
string
acceptTermsrequired
true
Accepts the Terms of Service and the Data Processing Agreement; required.
marketing
boolean
Opts in to marketing email.
POST/auth/loginSign in; returns a session token#

Body

emailrequired
string
passwordrequired
string
POST/auth/logoutEnd the session#
POST/auth/login/2faFinish sign-in with a code#

5 tries per sign-in (5 minutes), 10 wrong codes per person per 15 minutes (429). Returns a session like sign-in.

Body

mfaTokenrequired
string
From /auth/login when it answers { mfaRequired: true }.
code
string
6 digits from the authenticator app.
recoveryCode
string
Instead of code.
POST/auth/password/forgotEmail a password reset link#

Always 202, whether or not the address has an account; 5 per address and 30 per client address per hour (429).

Body

emailrequired
string
POST/auth/password/resetSet a new password with the emailed link#

Works once, for an hour; ends every session and returns a new one, like sign-in. 404 link_invalid otherwise.

Body

tokenrequired
string
From the link (rst_…).
passwordrequired
string
At least 10 characters.
POST/auth/email/verifyConfirm the address with the emailed link#

Body

tokenrequired
string
From the link (vfy_…).
GET/auth/invitations/:tokenLook up an invitation#
POST/auth/invitations/:token/acceptAccept an invitation#

Body

passwordrequired
string
New users: their new password; existing users: their password.
name
string
New users only.
acceptTerms
true
New users only; required for them.
marketing
boolean
New users only.
code
string
Existing users with two-step sign-in: the app's code (401 mfa_required asks for it).
recoveryCode
string
Or one of their recovery codes.

Public endpoints#

No authentication. Called by SDKs and browsers.

GET/datafiles/:sdkKey.jsonThe environment's datafile#

ETag and Cache-Control: public, max-age=10; If-None-Match gets 304. Put a CDN in front.

GET/stream/:sdkKeyLive updates (server-sent events)#

event: revision with { "revision": n } at once and after every publish, and a comment every 25 seconds. Fetch /datafiles/:sdkKey.json?rev=n on each. Never cached; 503 past the server's connection limit (poll instead).

GET/sdk/v1/liftcanary.jsThe website snippet bundle#

5-minute cache with ETag. Upload it to your CDN in production.

GET/sdk/v1/editor.jsThe visual editor#

Loaded by the snippet only on #liftcanary_editor=… pages, from the same origin as the snippet.

GET/editor/sessions/:tokenThe visual editor's variations#

With an editor session token: { flag, variations: [{ key, name, editable, css, visual }], expiresAt }. 401 once it expired.

PUT/editor/sessions/:token/variations/:keySave a variation's visual changes#

Body { "visual": [...] } (see visual changes); publishes. The original (control) can't be changed: 409.

GET/geoCountry, region and city of the caller, from CDN headers#
GET/healthHealth check (liveness)#
GET/readyReadiness#

{ ok, checks: { database, warehouse } }; 503 when one fails. See Health and monitoring.