API
API overview
Authentication, errors, concurrency and conventions of the REST API.
The REST API does everything the dashboard does: projects, environments, flags and their targeting, audiences, locations, goals, experiments, results, websites, team and tokens. Use it from CI to create flags with a release, from scripts to report results, or to build your own tooling.
Base URL and format#
- Management endpoints live under
https://api.liftcanary.com/v1(your own address when self-hosting). - Requests and responses are JSON. Send
Content-Type: application/jsonwith a body; bodies are limited to 1 MB. - Projects, flags, audiences, locations and goals are addressed by their key; experiments by id.
- Keys are 1–64 characters of
a-z,0-9,_and-, starting with a letter or digit. - Times are ISO 8601 in UTC.
Authentication#
Create an API token in Settings → API tokens and send it as a bearer token:
curl https://api.liftcanary.com/v1/projects \
-H "Authorization: Bearer $LIFTCANARY_TOKEN"A token acts with its role: a viewer token can only read, an editor token can change configuration, an admin token can also manage people and tokens (see Roles). Every request is scoped to the token's organization; another organization's resources answer 404, never 403, so their existence isn't revealed.
Errors#
Errors have a machine-readable error code and a human message. Validation errors list every problem with its field path:
{
"error": "validation_failed",
"message": "request is invalid",
"issues": [
{ "path": "rules.0.allocation", "message": "weights must sum to 10000 (got 9000)" },
{ "path": "rules.1.conditions", "message": "unknown segment \"vip\"" }
]
}| Status | error | When |
|---|---|---|
| 400 | invalid_json | The body isn't valid JSON (invalid_if_match: a malformed If-Match header). |
| 401 | unauthorized | Missing, unknown or revoked token or session. |
| 403 | forbidden | The token's role can't do this. |
| 404 | not_found | No such resource in your organization, or no such route. |
| 409 | conflict | A key is taken, or the change would break something that depends on it. Specific codes include variation_in_running_experiment, not_running, already_stopped and last_owner. |
| 412 | version_mismatch | If-Match didn't match: someone changed it since you read it. |
| 413 | payload_too_large | Body over 1 MB. |
| 422 | validation_failed | The body is well-formed but invalid; see issues. |
| 429 | too_many_attempts | Too many failed sign-ins. |
| 503 | analytics_unavailable | Results were requested but the analytics warehouse isn't configured or reachable. |
Concurrency: If-Match#
A flag's targeting in an environment has a version that goes up with every change. Reading a flag returns it per environment; writing the configuration returns the new one in the ETag header. Send it back with If-Match:
PUT /v1/projects/web/flags/new_checkout/environments/production
If-Match: "7"
Content-Type: application/json
{ "enabled": true, "offVariation": "off", "rules": [ … ] }If someone saved in between, you get 412 instead of overwriting their change: read the flag again, reapply your change, retry. Without If-Match the last write wins.
Publishing#
Every change that affects SDKs publishes a new datafile in the same transaction: the environment's revision is bumped first (so concurrent publishes are serialized), then the datafile is built and stored. When the API answers, the change is live on the CDN within its cache time (about 10 seconds), and SDKs pick it up on their next refresh.
Audit trail#
Changes made with a token are recorded in the audit log under the token's name, with the configuration before and after: GET /v1/audit-log.
Next#
- Endpoint reference: every endpoint and its body.
- Datafile format: what SDKs download.
- Events and the collector: what SDKs send.