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
/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:
curl https://lift.example.com/api/public/v1/sites \
-H "Authorization: Bearer lift_sk_YOUR_API_KEY"| Scope | Allows |
|---|---|
| read | Every GET operation. |
| write | Everything, 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:
{
"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:
{
"error": {
"code": "validation",
"message": "Please check the highlighted fields.",
"fieldErrors": { "name": ["Required"] }
}
}| Status | Code | Meaning |
|---|---|---|
| 401 | unauthorized | The API key is missing, malformed, revoked or expired. |
| 402 | plan_limit | The organization's plan does not include this. |
| 403 | forbidden | The API key lacks the required scope. |
| 404 | not_found | The object does not exist in your organization. |
| 409 | conflict | The operation conflicts with the current state. |
| 422 | validation | The request is malformed; see error.fieldErrors. |
| 429 | rate_limited | Too 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.
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:
| Header | Value |
|---|---|
| X-RateLimit-Limit | Requests allowed per minute for this key. |
| X-RateLimit-Remaining | Requests that can be made right now. |
| X-RateLimit-Reset | Seconds until the full budget is available again. |
| Retry-After | On 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.
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /clients | List clients | read |
| GET | /clients/{clientId} | Get a client | read |
Sites
Websites the snippet is installed on.
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /sites | List sites | read |
| GET | /sites/{siteId} | Get a site | read |
Goals
Conversions measured on a site.
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /sites/{siteId}/goals | List goals of a site | read |
| POST | /sites/{siteId}/goals | Create a goal | write |
| GET | /goals/{goalId} | Get a goal | read |
| PATCH | /goals/{goalId} | Update a goal | write |
| POST | /goals/{goalId}/archive | Archive a goal | write |
| POST | /goals/{goalId}/restore | Restore an archived goal | write |
Experiments
Experiments and their lifecycle.
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /sites/{siteId}/experiments | List experiments of a site | read |
| POST | /sites/{siteId}/experiments | Create an experiment | write |
| GET | /sites/{siteId}/experiments/by-key/{key} | Get an experiment by its key | read |
| GET | /experiments/{experimentId} | Get an experiment | read |
| PATCH | /experiments/{experimentId} | Update an experiment | write |
| PUT | /experiments/{experimentId}/goals | Replace the goals of an experiment | write |
| POST | /experiments/{experimentId}/start | Start or resume an experiment | write |
| POST | /experiments/{experimentId}/pause | Pause a running experiment | write |
| POST | /experiments/{experimentId}/stop | Stop an experiment | write |
Variants
Page variants of an experiment, as lists of DOM mutations.
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /experiments/{experimentId}/variants | List variants of an experiment | read |
| POST | /experiments/{experimentId}/variants | Add a variant | write |
| GET | /variants/{variantId} | Get a variant | read |
| PATCH | /variants/{variantId} | Update a variant | write |
| DELETE | /variants/{variantId} | Delete a variant | write |
Results
Statistics of an experiment.
| Method | Path | Description | Scope |
|---|---|---|---|
| GET | /experiments/{experimentId}/results | Get the results of an experiment | read |
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.
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 withPOST /experiments/{experimentId}/variants, then callPOST /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
allocationandkeycannot be changed.
Read results
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