Skip to content

REST API reference

Authentication, the response envelope, pagination, rate limits and every endpoint of the public API.

Overview#

The REST API lists your sites, manages their goals, experiments and variants, and reads results — the same operations the dashboard performs, under the same rules. It is included in the Growth and Agency plans.

All paths are relative to /api/public/v1 on the origin of your dashboard. Requests and responses are JSON. Ids are UUIDs and timestamps are ISO 8601 strings.

OpenAPI document

The complete, machine-readable description — every parameter, request body and response schema — is served as OpenAPI 3.1 at /api/public/v1/openapi.json. It is generated from the schemas the API validates with, so it cannot drift from the implementation. Use it to generate a client or to explore the API in the tool of your choice.

Authentication#

Create a key under Settings → API keys (admin role). The full key is shown once, when it is created; only a hash is stored afterwards. Send it as a bearer token:

bash
curl https://lift.example.com/api/public/v1/sites \
  -H "Authorization: Bearer lift_sk_YOUR_API_KEY"
ScopeAllows
readEvery GET operation.
writeEverything, including creating and changing experiments. Implies read. Acts with the rights of a member.
  • A key belongs to one organization and can only see that organization's sites. An id from another organization answers 404, never 403.
  • Keys start with lift_sk_. They are secrets: keep them on a server, never in a browser or a mobile app. The public site key in the install tag (lift_pk_…) is a different thing and is not accepted here.
  • Revoke a key from the same page. It stops working immediately. Every change made through the API is in the audit log under the key's name.

Responses and errors#

A successful response wraps its result in data. Lists add a pagination object:

200 OKjson
{
  "data": [
    {
      "id": "0198c1dd-…",
      "name": "Main site",
      "domain": "example.com",
      "clientLabel": null,
      "status": "active",
      "snippetLastSeenAt": "2026-01-01T00:00:00.000Z",
      "runningExperiments": 2,
      "pendingReviews": 1,
      "createdAt": "2025-11-03T09:12:44.000Z"
    }
  ],
  "pagination": { "limit": 25, "hasMore": true, "nextCursor": "eyJ…" }
}

A failed request answers with the matching HTTP status and an error object. code is stable and meant for programs; message is meant for people. Validation failures list the offending fields:

422 Unprocessable Contentjson
{
  "error": {
    "code": "validation",
    "message": "Please check the highlighted fields.",
    "fieldErrors": { "name": ["Required"] }
  }
}
StatusCodeMeaning
401unauthorizedThe API key is missing, malformed, revoked or expired.
402plan_limitThe organization's plan does not include this.
403forbiddenThe API key lacks the required scope.
404not_foundThe object does not exist in your organization.
409conflictThe operation conflicts with the current state.
422validationThe request is malformed; see error.fieldErrors.
429rate_limitedToo many requests; retry after Retry-After seconds.

Every response carries an X-Request-Id header. Quote it when you contact support about a request.

Pagination#

List operations return 25 items by default and accept a limit of up to 100. When pagination.hasMore is true, pass pagination.nextCursor as the cursor parameter to get the next page. Cursors are opaque: do not build or modify them.

Reading every pagejs
const BASE = 'https://lift.example.com/api/public/v1';
const headers = { Authorization: `Bearer ${process.env.LIFT_API_KEY}` };

async function listAll(path) {
  const items = [];
  let cursor = null;
  for (;;) {
    const url = new URL(BASE + path);
    url.searchParams.set('limit', '100');
    if (cursor) url.searchParams.set('cursor', cursor);

    const response = await fetch(url, { headers });
    if (response.status === 429) {
      const wait = Number(response.headers.get('retry-after') ?? 1);
      await new Promise((resolve) => setTimeout(resolve, wait * 1000));
      continue; // repeat the same request, with the same cursor
    }
    const body = await response.json();
    if (!response.ok) throw new Error(body.error.code + ': ' + body.error.message);

    items.push(...body.data);
    if (!body.pagination.hasMore) return items;
    cursor = body.pagination.nextCursor;
  }
}

const experiments = await listAll('/sites/SITE_ID/experiments');

Rate limits#

Each key may make 120 requests per minute. Authenticated responses report where you stand:

HeaderValue
X-RateLimit-LimitRequests allowed per minute for this key.
X-RateLimit-RemainingRequests that can be made right now.
X-RateLimit-ResetSeconds until the full budget is available again.
Retry-AfterOn a 429 only: seconds to wait before the next request.

On a 429, wait for Retry-After and repeat the request. The pagination example above does exactly that.

Endpoints#

Paths are relative to /api/public/v1. Request and response schemas for each operation are in the OpenAPI document.

Clients

The companies an agency works for. Each site belongs to one client.

MethodPathDescriptionScope
GET/clientsList clientsread
GET/clients/{clientId}Get a clientread

Sites

Websites the snippet is installed on.

MethodPathDescriptionScope
GET/sitesList sitesread
GET/sites/{siteId}Get a siteread

Goals

Conversions measured on a site.

MethodPathDescriptionScope
GET/sites/{siteId}/goalsList goals of a siteread
POST/sites/{siteId}/goalsCreate a goalwrite
GET/goals/{goalId}Get a goalread
PATCH/goals/{goalId}Update a goalwrite
POST/goals/{goalId}/archiveArchive a goalwrite
POST/goals/{goalId}/restoreRestore an archived goalwrite

Experiments

Experiments and their lifecycle.

MethodPathDescriptionScope
GET/sites/{siteId}/experimentsList experiments of a siteread
POST/sites/{siteId}/experimentsCreate an experimentwrite
GET/sites/{siteId}/experiments/by-key/{key}Get an experiment by its keyread
GET/experiments/{experimentId}Get an experimentread
PATCH/experiments/{experimentId}Update an experimentwrite
PUT/experiments/{experimentId}/goalsReplace the goals of an experimentwrite
POST/experiments/{experimentId}/startStart or resume an experimentwrite
POST/experiments/{experimentId}/pausePause a running experimentwrite
POST/experiments/{experimentId}/stopStop an experimentwrite

Variants

Page variants of an experiment, as lists of DOM mutations.

MethodPathDescriptionScope
GET/experiments/{experimentId}/variantsList variants of an experimentread
POST/experiments/{experimentId}/variantsAdd a variantwrite
GET/variants/{variantId}Get a variantread
PATCH/variants/{variantId}Update a variantwrite
DELETE/variants/{variantId}Delete a variantwrite

Results

Statistics of an experiment.

MethodPathDescriptionScope
GET/experiments/{experimentId}/resultsGet the results of an experimentread

Common tasks#

Create and start an experiment

Creating an experiment makes a draft with a control variant (“Original”) and any challengers you include. A variant is a name and a list of mutations; HTML in mutations is sanitized on save.

bash
curl -X POST https://lift.example.com/api/public/v1/sites/SITE_ID/experiments \
  -H "Authorization: Bearer lift_sk_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Hero headline",
    "key": "hero-headline",
    "allocation": "bandit",
    "urlRules": { "include": [{ "match": "exact", "value": "/" }], "exclude": [] }
  }'
  • Set the goals with PUT /experiments/{experimentId}/goals, add variants with POST /experiments/{experimentId}/variants, then call POST /experiments/{experimentId}/start.
  • Starting runs the launch checks. If one fails the answer is a 422 whose error lists what to fix. Starting a paused experiment resumes it; any other status answers 409.
  • While an experiment is running or paused, its allocation and key cannot be changed.

Read results

bash
curl "https://lift.example.com/api/public/v1/experiments/EXPERIMENT_ID/results?segments=device,country" \
  -H "Authorization: Bearer lift_sk_YOUR_API_KEY"

The response has, per variant, visitors, conversions, the posterior conversion rate with its credible interval, probabilityBest, expectedLoss and the lift over control; plus the sample-ratio check, the decision, a daily series and segment breakdowns. Without goalId the primary goal is analyzed. segments defaults to device and visitor type; pass none to leave the breakdowns out. The fields are explained in Reading the results.

Stop an experiment

POST /experiments/{experimentId}/stop ends an experiment. Send {"winnerVariantId": "…"} to declare a winner and keep serving it to all targeted visitors, {"keepControl": true} to record the original as the winner, or no body for an inconclusive result.

React to changes instead of polling

To be told when an experiment finishes or a variant needs review, subscribe to webhooks rather than polling the results endpoint.