Skip to content

Management API (Beta)

The Experiment management API can be used to programmatically create and control flags and experiments.

Experiment Management API in Beta

This API is in Beta. If you would like to try out an early version of the API please reach out to us.

Endpoints

Name
Description
List experiments List of experiments including their configuration details.
List deployments List deployments that experiments can be assigned to.
Get experiment details Get the configuration details of an experiment.
Create experiment Create a new experiment.
Activate experiment Activate a inactive experiment.
Deactivate experiment Deactivate an active experiment.
Rollout weights Update the rollout weights for an experiment.

Authorization

The management API uses the HTTP Authorization header for authentication.

The header must be: Authorization: Bearer <management-api-key>.

Management API Keys

Management API keys are different from the deployment keys used to fetch flag variants. They're created and managed via the Management API link in the Experiment sidebar.

Conventions

Status Codes

The API uses meaningful status codes to communicate the result of requests.

Code Meaning
200 Success!
400 Input is missing or invalid
401 Invalid or revoked API key
403 API key does not have access to the specified environment

Cursors

Endpoints that list resources such as /experiments/list will only return a limited number of items per request. In order to fetch the next page of items the nextCursor value returned from the first request must be passed as the cursor parameter of the next request. In this way multiple requests can be chained together to fetch the total set of items.


List experiments

GET https://management-api.experiment.amplitude.com/experiments/list

Fetch a list of experiments including their configuration details. Results are ordered with the most recently created experiments first.

Query parameters

Name
Description
limit The max number of experiments to be returned. Capped at 1000.
cursor The offset to start the "page" of results from.

Response

A successful request returns a 200 OK response and a list of experiments encoded as JSON in the response body.

Example cURL

curl --request GET \
  --url 'https://management-api.experiment.amplitude.com/experiments/list?limit=1000' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <management-api-key>'

List deployments

GET https://management-api.experiment.amplitude.com/deployments/list

Fetch a list of deployments that experiments can be assigned to.

Query parameters

Name
Description
limit The max number of deployments to be returned. Capped at 1000.
cursor The offset to start the "page" of results from.

Response

A successful request returns a 200 OK response and a list of deployments encoded as JSON in the response body.

Example cURL

curl --request GET \
  --url 'https://management-api.experiment.amplitude.com/deployments/list?limit=1000' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <management-api-key>'

Get experiment details

GET https://management-api.experiment.amplitude.com/experiments/{id}

Fetch the configuration details of an experiment.

Path variables

Name
Description
id Required. String. The experiment's ID.

Response

A successful request returns a 200 OK response and a JSON object with the experiment's details.

Example cURL

curl --request GET \
  --url 'https://management-api.experiment.amplitude.com/experiments/<id>' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <management-api-key>'

Create experiment

POST https://management-api.experiment.amplitude.com/experiments/new

Create a new experiment.

Request body

Name
Requirement Type Description
projectId Required string The project's ID.
key Required string The flag or experiment key.
description Optional string Description for the experiment.
variants Optional object array Array of variants.
bucketingKey Optional string The user property to bucket the user by.
rolloutWeights Optional object Rollout weights for non-targeted users. The object should be a mapping from variant key to rollout weight as an integer e.g. { "control": 1, "treatment": 1 }.
targetSegments Optional object See the targetSegments table for more information.
stickyBucketing Optional boolean If true, the experiment will use sticky bucketing.
deployments Optional string array Array of deployments that the experiment should be assigned to.

variants

The variants field contains these objects.

Name
Requirement Type Description
key Required string The key (a.k.a value) of the variant
payload Optional string Optional payload. Value must be a valid JSON element.
name Optional string The variant name.
description Optional string The variant description.

targetSegments

The targetSegments field contains these objects.

Name
Requirement Type Description
name Optional string The segment name.
conditions Required object array Array of conditions.
percentage Optional number The allocation percentage for users who match a condition.
rolloutWeights Optional object A map from variant key to rollout weight e.g. { "control": 1, "treatment": 1 }.

conditions

The conditions field contains these objects.

Name
Requirement Type Description
type Required string Must have value: property
prop Required string The property to use in the condition
op Required string The operation to use in this condition.
values Required string array The values to use in the operation.

op

An string value representing operations on a property value. Possible values are: is, is not, contains, does not contain, less, less or equal, greater, greater or equal, glob match, glob does not match

Response

A successful request returns a 200 OK response and a JSON object with the experiment's details.

Example cURL

curl --request POST \
  --url 'https://management-api.experiment.amplitude.com/experiments/new' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <management-api-key>'
  --data '{"projectId":"<projectId>","key":"<key>"}'

Activate experiment

POST https://management-api.experiment.amplitude.com/experiments/{id}/activate

Activate a inactive experiment.

Path variables

Name
Description
id Required. String. The experiment's ID.

Example cURL

curl --request POST \
  --url 'https://management-api.experiment.amplitude.com/experiments/<id>/activate' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <management-api-key>'

Deactivate experiment

POST https://management-api.experiment.amplitude.com/experiments/{id}/deactivate

Deactivate an active experiment.

Path variables

Name
Description
id Required. String. The experiment's ID.

Example cURL

curl --request POST \
  --url 'https://management-api.experiment.amplitude.com/experiments/<id>/deactivate' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <management-api-key>'

Rollout weights

POST https://management-api.experiment.amplitude.com/experiments/{id}/rollout-weights

Update the rollout weights for an experiment.

Path variables

Name
Description
id Required. String. The experiment's ID.

Request body

Name
Requirement Type Description
rolloutWeights Required object A map from variant key to rollout weight e.g. {"control": 1,"treatment":1}.

Example cURL

curl --request POST \
  --url 'https://management-api.experiment.amplitude.com/experiments/<id>/rollout-weights' \
  --header 'Accept: application/json' \
  --header 'Authorization: Bearer <management-api-key>'
  --data '{"rolloutWeights":{"control": 1,"treatment":1}}'

Last update: 2022-06-30