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/projects - POST
/v1/projects - GET
/v1/projects/:project - GET
/v1/projects/:project/integrations - PUT
/v1/projects/:project/integrations - GET
/v1/projects/:project/webhooks/:provider - POST
/v1/projects/:project/environments/:env/webhooks/:provider - PATCH
/v1/projects/:project/environments/:env/webhooks/:provider - DELETE
/v1/projects/:project/environments/:env/webhooks/:provider - GET
/v1/projects/:project/consent-banner - PUT
/v1/projects/:project/consent-banner - PATCH
/v1/projects/:project - DELETE
/v1/projects/:project - GET
/v1/projects/:project/visitors/:id - DELETE
/v1/projects/:project/visitors/:id - POST
/v1/projects/:project/environments - PATCH
/v1/projects/:project/environments/:env - POST
/v1/projects/:project/environments/:env/sdk-key - DELETE
/v1/projects/:project/environments/:env - GET
/v1/projects/:project/environments/:env/datafile - GET
/v1/projects/:project/environments/:env/datafiles - GET
/v1/projects/:project/environments/:env/activity
/v1/projectsList projects#/v1/projectsCreate a project#Body
keyrequiredkey | Project key. |
namerequiredstring | Display name. |
environments[{ key, name }] | 1–20 environments. Default: development and production. |
/v1/projects/:projectA project with its environments, SDK keys and current revisions#/v1/projects/:project/integrationsAnalytics integrations#Every tool (ga4, gtm, segment, mixpanel) with enabled, eventName, defaultEventName, and sendNames.
/v1/projects/:project/integrationsChange analytics integrations#Admins. { ga4?: { enabled, eventName }, …, sendNames? }; publishes. See Integrations.
/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.
/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
fieldstring | 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). |
secretstring | Paddle and Stripe: the signing secret (pdl_ntfset_…, whsec_…). It can also come later with PATCH. |
/v1/projects/:project/environments/:env/webhooks/:providerChange the field, or the signing secret#Admins.
Body
fieldstring | Chargebee: an API name, cf_ and lowercase letters, digits or _. Paddle, Stripe: letters, digits or _, not starting with a digit (Stripe: up to 40). |
secretstring | Paddle and Stripe: the signing secret, kept encrypted and never returned. |
/v1/projects/:project/environments/:env/webhooks/:providerDisconnect a billing system#Admins. The provider's calls are refused from then on.
/v1/projects/:project/consent-bannerConsent banner design#The design of LiftCanary's consent banner; {} while it's LiftCanary's default.
/v1/projects/:project/consent-bannerChange the consent banner#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.
/v1/projects/:projectRename a project#Body
namerequiredstring | Display name. The key can't change. |
/v1/projects/:projectDelete a project (admin)#Deletes its environments, flags, audiences, locations, goals, experiments and collected events, and its SDK keys stop working.
/v1/projects/:project/visitors/:idWhat's stored about a visitor (anonymous id or user id, with linked ids): { ids, exposures, events, firstSeen, lastSeen } (admin)#/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.
/v1/projects/:project/environmentsAdd an environment#Existing flags start switched off in the new environment.
Body
keyrequiredkey | Environment key. |
namerequiredstring | Display name. |
/v1/projects/:project/environments/:envRename an environment#Body
namerequiredstring | Display name. The key and SDK key stay the same. |
/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.
/v1/projects/:project/environments/:envDelete an environment (admin)#A project keeps at least one environment.
/v1/projects/:project/environments/:env/datafileThe current datafile#Add ?revision=n for a past one.
/v1/projects/:project/environments/:env/datafilesRevision history (latest 100)#/v1/projects/:project/environments/:env/activityWhen events last arrived (install check)#Flags#
- GET
/v1/projects/:project/flags - POST
/v1/projects/:project/flags - GET
/v1/projects/:project/flags/:flag - PATCH
/v1/projects/:project/flags/:flag - DELETE
/v1/projects/:project/flags/:flag - PUT
/v1/projects/:project/flags/:flag/environments/:env - POST
/v1/projects/:project/flags/:flag/environments/:env/toggle - POST
/v1/projects/:project/flags/:flag/variations/:variation/rename
/v1/projects/:project/flagsList flags with their kind and per-environment on/off state#/v1/projects/:project/flagsCreate a flag#Body
keyrequiredkey | Flag key. |
namerequiredstring | Display name. |
descriptionstring | 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. |
redirectobject | 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). |
{
"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" } }
]
}/v1/projects/:project/flags/:flagA flag with its targeting in every environment (each with its version)#/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.
/v1/projects/:project/flags/:flagArchive a flag#It disappears from datafiles.
/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
enabledrequiredboolean | The on/off switch. |
offVariationrequiredkey | Served when off. |
defaultVariationkey | null | Served when on and no rule matches. Default: the off variation. |
overrides{ [userId]: variation } | Pinned users. |
rulesRule[] | Up to 100, in order. Each: key, type (rollout | experiment), conditions?, traffic (0–10000), allocation (weights summing to 10000). |
{
"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 }]
}
]
}/v1/projects/:project/flags/:flag/environments/:env/toggleKill switch#Body
enabledrequiredboolean | On or off; rules are kept. |
/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
keyrequiredkey | The new key. |
Audiences (segments)#
The API calls audiences segments; conditions refer to them with { "segment": "key" }.
- GET
/v1/projects/:project/segments - POST
/v1/projects/:project/segments - GET
/v1/projects/:project/segments/:segment - PATCH
/v1/projects/:project/segments/:segment - DELETE
/v1/projects/:project/segments/:segment
/v1/projects/:project/segmentsList audiences#/v1/projects/:project/segmentsCreate an audience#Body
keyrequiredkey | Audience key. |
namerequiredstring | Display name. |
conditionsrequiredCondition | A condition tree. |
/v1/projects/:project/segments/:segmentAn audience#/v1/projects/:project/segments/:segmentChange name or conditions#Cycles between audiences are rejected.
/v1/projects/:project/segments/:segmentDelete an audience#409 while a flag or another audience uses it.
Locations#
- GET
/v1/projects/:project/locations - POST
/v1/projects/:project/locations - GET
/v1/projects/:project/locations/:location - PATCH
/v1/projects/:project/locations/:location - DELETE
/v1/projects/:project/locations/:location
/v1/projects/:project/locationsList locations, each with where it's used#/v1/projects/:project/locationsCreate a location#Body
keyrequiredkey | Location key. |
namerequiredstring | Display name. |
descriptionstring | Optional. |
includerequiredUrlMatch[] | 1–50 rules: { type, value, caseSensitive? }. |
excludeUrlMatch[] | Up to 50 rules. |
triggerTrigger | null | pageload (default), click/visible/element with a selector, or manual. See triggers. |
/v1/projects/:project/locations/:locationA location with its usage#/v1/projects/:project/locations/:locationChange a location#Only the fields you send change. A trigger is refused while a redirect test uses the location.
/v1/projects/:project/locations/:locationDelete a location#409 while anything uses it; the message lists what.
Goals#
- GET
/v1/projects/:project/goals - POST
/v1/projects/:project/goals - PATCH
/v1/projects/:project/goals/:goal - DELETE
/v1/projects/:project/goals/:goal
/v1/projects/:project/goalsGoals with recent event counts and usage, plus tracked events without a goal#/v1/projects/:project/goalsCreate a goal#Body
keyrequiredkey | Goal ID. |
namerequiredstring | Display name. |
eventKeyrequiredstring | Event it counts. |
descriptionstring | Optional. |
type"conversion" | "mean" | "ratio" | Default conversion. |
direction"increase" | "decrease" | Default increase. |
triggerGoalTrigger | Default { "kind": "code" }. See goal triggers. |
lagDaysinteger | Late conversions: days (0–30) its events keep counting after an experiment ends. Default 0. See Goals. |
/v1/projects/:project/goals/:goalChange a goal#/v1/projects/:project/goals/:goalDelete a goal#Experiments#
- GET
/v1/projects/:project/experiments - POST
/v1/projects/:project/experiments - POST
/v1/projects/:project/deploys - POST
/v1/projects/:project/flags/:flag/editor-sessions - GET
/v1/projects/:project/experiments/:id - PATCH
/v1/projects/:project/experiments/:id - POST
/v1/projects/:project/experiments/:id/start - POST
/v1/projects/:project/experiments/:id/stop - POST
/v1/projects/:project/experiments/:id/guardrails/check - GET
/v1/projects/:project/experiments/:id/report - GET
/v1/projects/:project/experiments/:id/breakdown - GET
/v1/projects/:project/experiments/:id/results - GET
/v1/projects/:project/flags/:flag/environments/:env/results
/v1/projects/:project/experimentsList experiments#?status=draft|running|stopped; ?summary=0 skips the headline results.
/v1/projects/:project/experimentsCreate an experiment#Body: see Experiments; no-code and A/A tests: No-code tests.
/v1/projects/:project/deploysCreate a deploy (personalization)#CSS/JS for an audience on some pages, on its own flag. See No-code tests.
/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.
/v1/projects/:project/experiments/:idAn experiment#/v1/projects/:project/experiments/:idChange an experiment#Body
namestring | |
hypothesisstring | |
primaryMetricmetric | null | |
secondaryMetricsmetric[] | |
confidenceLevel80 | 90 | 95 | 99 | |
guardrailsguardrail[] | 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. |
/v1/projects/:project/experiments/:id/startStart a draft#/v1/projects/:project/experiments/:id/stopStop#Body
shipvariation | null | Give everyone in the audience this variation from now on; null just ends the test. |
/v1/projects/:project/experiments/:id/guardrails/checkCheck guardrails now#/v1/projects/:project/experiments/:id/reportEvery goal, the funnel and guardrails#/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.
/v1/projects/:project/experiments/:id/resultsOne metric#?metric=<eventKey>&type=conversion|mean|ratio; default: the primary metric.
/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/websites - PUT
/v1/projects/:project/environments/:env/websites
/v1/projects/:project/environments/:env/websitesWebsites with status, plus discovered origins#/v1/projects/:project/environments/:env/websitesSet websites and mode#Body
websitesstring[] | Patterns: host, *.domain or host:port. |
mode"monitor" | "enforce" | enforce needs admin and at least one website. |
Organization, team and tokens#
- GET
/v1/me - POST
/v1/me/organization - PATCH
/v1/me - POST
/v1/me/terms - PUT
/v1/me/marketing - GET
/v1/organization/data-plane - PUT
/v1/organization/data-plane - POST
/v1/organization/data-plane/license-key - POST
/v1/organization/data-plane/check - GET
/v1/me/deletion - DELETE
/v1/me - POST
/v1/me/2fa/setup - POST
/v1/me/2fa/enable - POST
/v1/me/2fa/recovery-codes - POST
/v1/me/2fa/disable - POST
/v1/me/email/verification - PATCH
/v1/me/notifications - POST
/v1/me/password - GET
/v1/me/sessions - DELETE
/v1/me/sessions - DELETE
/v1/me/sessions/:id - PATCH
/v1/organization - GET
/v1/usage - GET
/v1/billing - POST
/v1/billing/checkout - POST
/v1/billing/change - POST
/v1/billing/cancel - POST
/v1/billing/portal - GET
/v1/members - PATCH
/v1/members/:userId - DELETE
/v1/members/:userId - GET
/v1/invitations - POST
/v1/invitations - DELETE
/v1/invitations/:id - GET
/v1/api-tokens - POST
/v1/api-tokens - DELETE
/v1/api-tokens/:id - GET
/v1/audit-log
/v1/meThe current user, organization, role and other organizations#/v1/me/organizationSwitch organization (sessions)#Body
organizationIdrequireduuid |
/v1/meChange your name (sessions)#Body
namerequiredstring | 1–100 characters. |
/v1/me/termsAccept the current Terms of Service after they changed (sessions)#Body
versionrequiredstring | user.terms.currentVersion from GET /v1/me; 409 terms_changed if it's no longer current. |
/v1/me/marketingMarketing email on or off (sessions)#Body
optInrequiredboolean |
/v1/organization/data-planeHybrid deployment: whether it's enabled, the data plane address, whether a license key was issued (admins)#/v1/organization/data-planeSet or clear the data plane address (owners; hybrid only)#Body
urlrequiredstring | null | HTTPS address of your data plane; null disconnects. |
/v1/organization/data-plane/license-keyIssue a new license key, returned once; the previous key stops working (owners; hybrid only)#/v1/organization/data-plane/checkCheck that the data plane answers signed requests: { ok, error? } (admins)#/v1/me/deletionWhat deleting your account would delete (erase), leave (leave) or block it (blocked: you're the only owner of a team) (sessions)#/v1/meDelete your account for good (sessions); 409 sole_owner while blocked#Body
passwordrequiredstring | |
codestring | With two-step sign-in. |
recoveryCodestring | Instead of code. |
/v1/me/2fa/setupStart setting up two-step sign-in (sessions)#Returns { secret, otpauthUri } for the authenticator app; not active until enabled.
/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
coderequiredstring | The first code from the app. |
passwordrequiredstring | The account's password. |
/v1/me/2fa/recovery-codesNew recovery codes (sessions)#Body
coderequiredstring | A current code. |
/v1/me/2fa/disableTurn two-step sign-in off (sessions)#Body
passwordrequiredstring | |
codestring | |
recoveryCodestring | Instead of code. |
/v1/me/email/verificationSend the confirmation email again (sessions)#3 per hour; the earlier link stops working.
/v1/me/notificationsChoose notification emails (sessions)#Body
guardrailsboolean | |
scheduleboolean | |
usageboolean |
/v1/me/passwordChange your password (sessions)#Signs out every other session of yours, in every organization.
Body
currentPasswordrequiredstring | |
newPasswordrequiredstring | At least 10 characters. |
/v1/me/sessionsYour active sessions (sessions)#Each with current, organization, createdAt and lastUsedAt.
/v1/me/sessionsSign out every other session#/v1/me/sessions/:idSign out one session#Not the current one: use sign-out for that.
/v1/organizationRename the organization (admin)#Body
namerequiredstring | 1–100 characters. |
/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.
/v1/billingPlan, limits and subscription#plan, testedVisitors, projects, seats, features, subscription (status, interval, currentPeriodEnd, cancelAtPeriodEnd) and current usage. plansEnforced: false on self-hosted installations.
/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. |
/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" |
/v1/billing/cancelCancel at the end of the period (admin)#Then Free. POST /v1/billing/resume keeps the subscription. Nothing is deleted.
/v1/billing/portalInvoices and payment method (admin)#Returns the url of the payment provider's customer portal.
/v1/membersMembers#/v1/members/:userIdChange a role#Body
rolerequired"viewer" | "editor" | "admin" | "owner" | Up to your own role. |
/v1/members/:userIdRemove a member#The last owner can't be removed.
/v1/invitationsPending invitations#/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
emailrequiredstring | |
rolerequiredrole |
/v1/invitations/:idCancel an invitation#/v1/api-tokensAPI tokens (without secrets)#/v1/api-tokensCreate an API token#The secret is in the response, once.
Body
namerequiredstring | |
rolerequired"viewer" | "editor" | "admin" |
/v1/api-tokens/:idRevoke a token#/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/signup - POST
/auth/login - POST
/auth/logout - POST
/auth/login/2fa - POST
/auth/password/forgot - POST
/auth/password/reset - POST
/auth/email/verify - GET
/auth/invitations/:token - POST
/auth/invitations/:token/accept
/auth/signupCreate an account and organization#Body
emailrequiredstring | |
passwordrequiredstring | At least 10 characters. |
namerequiredstring | |
organizationNamerequiredstring | |
acceptTermsrequiredtrue | Accepts the Terms of Service and the Data Processing Agreement; required. |
marketingboolean | Opts in to marketing email. |
/auth/loginSign in; returns a session token#Body
emailrequiredstring | |
passwordrequiredstring |
/auth/logoutEnd the session#/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
mfaTokenrequiredstring | From /auth/login when it answers { mfaRequired: true }. |
codestring | 6 digits from the authenticator app. |
recoveryCodestring | Instead of code. |
/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
emailrequiredstring |
/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
tokenrequiredstring | From the link (rst_…). |
passwordrequiredstring | At least 10 characters. |
/auth/email/verifyConfirm the address with the emailed link#Body
tokenrequiredstring | From the link (vfy_…). |
/auth/invitations/:tokenLook up an invitation#/auth/invitations/:token/acceptAccept an invitation#Body
passwordrequiredstring | New users: their new password; existing users: their password. |
namestring | New users only. |
acceptTermstrue | New users only; required for them. |
marketingboolean | New users only. |
codestring | Existing users with two-step sign-in: the app's code (401 mfa_required asks for it). |
recoveryCodestring | Or one of their recovery codes. |
Public endpoints#
No authentication. Called by SDKs and browsers.
- GET
/datafiles/:sdkKey.json - GET
/stream/:sdkKey - GET
/sdk/v1/liftcanary.js - GET
/sdk/v1/editor.js - GET
/editor/sessions/:token - PUT
/editor/sessions/:token/variations/:key - GET
/geo - GET
/health - GET
/ready
/datafiles/:sdkKey.jsonThe environment's datafile#ETag and Cache-Control: public, max-age=10; If-None-Match gets 304. Put a CDN in front.
/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).
/sdk/v1/liftcanary.jsThe website snippet bundle#5-minute cache with ETag. Upload it to your CDN in production.
/sdk/v1/editor.jsThe visual editor#Loaded by the snippet only on #liftcanary_editor=… pages, from the same origin as the snippet.
/editor/sessions/:tokenThe visual editor's variations#With an editor session token: { flag, variations: [{ key, name, editable, css, visual }], expiresAt }. 401 once it expired.
/editor/sessions/:token/variations/:keySave a variation's visual changes#Body { "visual": [...] } (see visual changes); publishes. The original (control) can't be changed: 409.
/geoCountry, region and city of the caller, from CDN headers#/healthHealth check (liveness)#/readyReadiness#{ ok, checks: { database, warehouse } }; 503 when one fails. See Health and monitoring.