Experiment Management API Flag Endpoints

Name
Description
List List of flags including their configuration details.
Get details Get the configuration details of a flag.
List versions List all versions for a flag.
Get version details Get a specific version for a flag.
List variants List all variants for a flag.
Get variant details Get a specific variant for a flag.
Get variant inclusions Get all inclusions (users) for a variant.
Create variant Create a new variant for a flag.
Edit variant Edit a variant for a flag.
Remove variant Remove a variant from a flag.
Add users to variant Add users to flag's variant.
Remove users from variant Remove users from flag's variant.
Remove all users from variant Remove all users from flag's variant.
Bulk remove users from variant Bulk remove users from experiment's variant.
List deployments List all deployments for a flag.
Create deployment Add a deployment for a flag.
Remove deployment Remove a deployment from a flag.
Edit Edit flag.
Create Create a new flag.

List

1GET https://experiment.amplitude.com/api/1/flags

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

Query parameters

Name Description
limit The max number of flags 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 flags encoded as JSON in the response body. createdAt and lastModifiedAt are in UTC in ISO 8601 format.

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

1{
2 "flags": [
3 {
4 "id": <id>,
5 "projectId": <projectId>,
6 "deployments": [<deploymentId>],
7 "key": "flag-key",
8 "name": "flag-name",
9 "description": "description",
10 "enabled": false,
11 "evaluationMode": "remote",
12 "bucketingKey": "amplitude_id",
13 "bucketingSalt": <bucketingSalt>,
14 "bucketingUnit": "User",
15 "createdBy": "abc@amplitude.com",
16 "lastModifiedBy": "abc@amplitude.com",
17 "createdAt":"2022-09-09T15:29:47.940Z",
18 "lastModifiedAt":"2023-01-25T11:43:41.073Z"
19 "variants": [
20 {
21 "key": "on"
22 }
23 ],
24 "rolloutPercentage": 0,
25 "rolloutWeights": {
26 "on": 1
27 },
28 "targetSegments": [
29 {
30 "name": "Segment 1",
31 "conditions": [
32 {
33 "prop": "city",
34 "op": "is",
35 "type": "property",
36 "values": []
37 }
38 ],
39 "percentage": 0,
40 "bucketingKey": "amplitude_id",
41 "rolloutWeights": {
42 "on": 1
43 }
44 }
45 ]
46 }
47 ],
48 "nextCursor": <cursorId>
49}

Get details

1GET https://experiment.amplitude.com/api/1/flags/<id>

Fetch the configuration details of a flag.

Path variables

Name Description
id Required. String. Flag's ID.

Response

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

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

1{
2 "id": <id>,
3 "projectId": <projectId>,
4 "deployments": [<deploymentId>],
5 "key": "flag-key",
6 "name": "flag-key",
7 "description": "feature flag access",
8 "enabled": true,
9 "evaluationMode": "remote",
10 "bucketingKey": "amplitude_id",
11 "bucketingSalt": "mHdQDzeE",
12 "bucketingUnit": "User",
13 "variants": [
14 {
15 "key": "on"
16 }
17 ],
18 "rolloutPercentage": 0,
19 "rolloutWeights": {
20 "on": 1
21 },
22 "targetSegments": [
23 {
24 "name": "Segment 1",
25 "conditions": [
26 {
27 "prop": "country",
28 "op": "is",
29 "type": "property",
30 "values": [
31 "United States"
32 ]
33 }
34 ],
35 "percentage": 0,
36 "bucketingKey": "amplitude_id",
37 "rolloutWeights": {
38 "on": 1
39 }
40 }
41 ],
42 "deleted": false
43}

List versions

1GET https://experiment.amplitude.com/api/1/flags/{id}/versions

Fetch a list of all versions for a flag.

Path variables

Name Description
id Required. String. Flag's ID.

Response

A successful request returns a 200 OK response and a list of flag's versions encoded as an array of JSON objects in the response body. Versions are sorted in a descending order.

1curl --request GET \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/versions' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'

1[
2 {
3 "createdAt": "2023-07-29T03:32:49.594Z",
4 "createdBy": <userId>,
5 "version": 3,
6 "flagConfig": {
7 "id": <id>,
8 "projectId": <projectId>,
9 "deployments": [<deploymentId>],
10 "key": "flag-key",
11 "name": "flag-key",
12 "description": "feature flag access",
13 "enabled": true,
14 "evaluationMode": "remote",
15 "bucketingKey": "amplitude_id",
16 "bucketingSalt": "mHdQDzeE",
17 "bucketingUnit": "User",
18 "variants": [
19 {
20 "key": "on"
21 }
22 ],
23 "rolloutPercentage": 0,
24 "rolloutWeights": {
25 "on": 1
26 },
27 "targetSegments": [ ...
28 {
29 "name": "Segment 1",
30 "conditions": [
31 {
32 "prop": "country",
33 "op": "is",
34 "type": "property",
35 "values": [
36 "United States"
37 ]
38 }
39 ],
40 "percentage": 0,
41 "bucketingKey": "amplitude_id",
42 "rolloutWeights": {
43 "on": 1
44 }
45 }
46 ]
47 }
48 },
49 {
50 "createdAt": "2023-07-29T03:32:39.494Z",
51 "createdBy": <userId>, ...
52 "version": 2,
53 "flagConfig": {
54 "id": <id>,
55 "projectId": <projectId>,
56 "deployments": [<deploymentId>],
57 "key": "flag-key",
58 "name": "flag-key",
59 "description": "feature flag access",
60 "enabled": false,
61 "evaluationMode": "remote",
62 "bucketingKey": "amplitude_id",
63 "bucketingSalt": "mHdQDzeE",
64 "bucketingUnit": "User",
65 "variants": [
66 {
67 "key": "on"
68 }
69 ],
70 "rolloutPercentage": 0,
71 "rolloutWeights": {
72 "on": 1
73 },
74 "targetSegments": [
75 {
76 "name": "Segment 1",
77 "conditions": [
78 {
79 "prop": "country",
80 "op": "is",
81 "type": "property",
82 "values": [
83 "United States"
84 ]
85 }
86 ],
87 "percentage": 0,
88 "bucketingKey": "amplitude_id",
89 "rolloutWeights": {
90 "on": 1
91 }
92 }
93 ]
94 }
95 },
96 {
97 "createdAt": "2023-07-29T03:30:45.703Z",
98 "createdBy": <userId>,
99 "version": 1,
100 "flagConfig": {
101 "id": <id>,
102 "projectId": <projectId>,
103 "deployments": [],
104 "key": "flag-key",
105 "name": "flag-key",
106 "description": "",
107 "enabled": false,
108 "evaluationMode": "remote",
109 "bucketingKey": "amplitude_id",
110 "bucketingSalt": "mHdQDzeE",
111 "bucketingUnit": "User",
112 "variants": [
113 {
114 "key": "on"
115 }
116 ],
117 "rolloutPercentage": 0,
118 "rolloutWeights": {
119 "on": 1
120 },
121 "targetSegments": []
122 }
123 }
124]

Get version details

1GET https://experiment.amplitude.com/api/1/flags/{id}/versions/{versionId}

Fetch details of a specific version of a flag.

Path variables

Name Description
id Required. String. Flag's ID.
versionId Required. String. The version's ID.

Response

A successful request returns a 200 OK response and a JSON object with details of the version.

1curl --request GET \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/versions/<versionId>' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'

1{
2 "createdAt": "2023-07-29T03:32:49.594Z",
3 "createdBy": <userId>,
4 "version": 3,
5 "flagConfig": {
6 "id": <id>,
7 "projectId": <projectId>,
8 "deployments": [<deploymentId>],
9 "key": "flag-key",
10 "name": "flag-key",
11 "description": "feature flag access",
12 "enabled": true,
13 "evaluationMode": "remote",
14 "bucketingKey": "amplitude_id",
15 "bucketingSalt": "mHdQDzeE",
16 "bucketingUnit": "User",
17 "variants": [
18 {
19 "key": "on"
20 }
21 ],
22 "rolloutPercentage": 0,
23 "rolloutWeights": {
24 "on": 1
25 },
26 "targetSegments": [
27 {
28 "name": "Segment 1",
29 "conditions": [
30 {
31 "prop": "country",
32 "op": "is",
33 "type": "property",
34 "values": [
35 "United States"
36 ]
37 }
38 ],
39 "percentage": 0,
40 "bucketingKey": "amplitude_id",
41 "rolloutWeights": {
42 "on": 1
43 }
44 }
45 ]
46 }
47}

List variants

1GET https://experiment.amplitude.com/api/1/flags/{id}/variants

Fetch a list of all variants for a flag.

Path variables

Name Description
id Required. String. Flag's ID.

Response

A successful request returns a 200 OK response and a list of variants encoded as an array of JSON objects in the response body.

1curl --request GET \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/variants' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'

1[
2 {
3 "key": "on",
4 "name": "",
5 "payload": {},
6 "description": "",
7 "rolloutWeight": 1
8 }
9]

Get variant details

1GET https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}

Fetch details of a specific variant of a flag.

Path variables

Name Description
id Required. String. Flag's ID.
variantKey Required. String. The variant's key.

Response

A successful request returns a 200 OK response and a JSON object with details of a flag variant.

1curl --request GET \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/variants/<variantKey>' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'

1{
2 "key": "on",
3 "name": "",
4 "payload": {},
5 "description": "",
6 "rolloutWeight": 1
7}

Get variant inclusions

1GET https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}/users

Fetch a list of inclusions for a specific variant of a flag.

Path variables

Name Description
id Required. String. Flag's ID.
variantKey Required. String. The variant's key.

Response

A successful request returns a 200 OK response and a list of inclusions of flag's variant as an array of JSON objects.

1curl --request GET \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/variants/<variantKey>/users' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'

1[
2 <user>@<your-company-email>,
3 <userId>
4]

Create variant

1POST https://experiment.amplitude.com/api/1/flags/{id}/variants

Create a new variant for a flag

Path variables

Name Description
id Required. String. Flag's ID.

Request body

Name
Requirement Type Description
key Required string The variant key.
description Optional string Description for the variant.
name Optional string Name for the variant.
payload Optional JSON The variant's payload. Must be a valid JSON element.
rolloutWeight Optional number Rollout weight for non-targeted users.

Example request

1{
2 "key": "new-variant-key",
3 "description": "optional description for variant",
4 "name": "optional name for variant",
5 "payload": {"variant-payload": "example payload"},
6 "rolloutWeight": 0
7}

Response

A successful request returns a 200 OK response and OK text.

Request

1curl --request POST \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/variants' \
3 --header 'Content-Type: application/json' \
4 --header 'Accept: application/json' \
5 --header 'Authorization: Bearer <management-api-key>' \
6 --data '{"key":"<key>","name":"<name>","description":"<description>","payload":"<payload>","rolloutWeight":<rolloutWeight>}'

Edit variant

1POST https://experiment.amplitude.com/api/1/flags/<id>/variants/<variantKey>

Edit a variant for a flag.

Path variables

Name Description
id Required. String. Flag's ID.
variantKey Required. String. The variant's key.

Example request

1{
2 "key": "updated-variant-key",
3 "description": "updated optional description for variant",
4 "name": "optional name for variant",
5 "payload": {"variant-payload": "example payload"},
6 "rolloutWeight": 0
7}

Request body

Name
Requirement Type Description
key Optional string The variant key.
description Optional string Description for the variant.
name Optional string Name for the variant.
payload Optional string Optional payload. Value must be a valid JSON element. This value replaces the existing value for the variant payload.
rolloutWeight Optional number Rollout weight for non-targeted users.

Response

A successful request returns a 200 OK response and OK text.

Request

1curl --request PATCH \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/variants/<variantKey>' \
3 --header 'Content-Type: application/json' \
4 --header 'Accept: application/json' \
5 --header 'Authorization: Bearer <management-api-key>' \
6 --data '{"key":"<key>","name":"<name>","description":"<description>","payload":"<payload>","rolloutWeight":<rolloutWeight>}'

Remove variant

1DELETE https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}

Remove a variant from a flag.

Path variables

Name Description
id Required. String. Flag's ID.
variantKey Required. String. The variant's key.

Response

A successful request returns a 200 OK response and OK text.

Request

1curl --request DELETE \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/variants/<variantKey>' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'

Add users to variant

1POST https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}/users

Add inclusions (users or devices) to flag's variant.

Path variables

Name Description
id Required. String. Flag's ID.
variantKey Required. String. The variant's key.

Request body

Name
Requirement Type Description
inclusions Required object Contains an string array of user or device ids.

Example request

1{
2 "inclusions": ["<user1>@<your-company-email>, <user2>@<your-company-email>, <userId>"]
3}

Response

A successful request returns a 200 OK response and OK text.

Request

1curl --request POST \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/variants/<variantKey>/users' \
3 --header 'Content-Type: application/json' \
4 --header 'Accept: application/json' \
5 --header 'Authorization: Bearer <management-api-key>' \
6 --data '{"inclusions":<["id1", "id2", "id3"]>}'

Remove users from variant

1DELETE https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}/users/{userIndex}

Remove inclusions (users or devices) from flag's variant.

Path variables

Name Description
id Required. String. Flag's ID.
variantKey Required. String. The variant's key.
userIndex Required. String. The user's index. Zero-indexed. Index-based array of users can be obtained via Get variant inclusions

Response

A successful request returns a 200 OK response and OK text.

Request

1curl --request DELETE \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/variants/<variantKey>/users/<userIndex>' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'

Remove all users from variant

1DELETE https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}/users

Remove all inclusions (users or devices) from flag's variant.

Path variables

Name
Description
id Required. String. Flag's ID.
variantKey Required. String. The variant's key.

Response

A successful request returns a 200 OK response and OK text.

Request

1curl --request DELETE \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/variants/<variantKey>/users' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'

Bulk remove users from variant

1DELETE https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}/bulk-delete-users

Bulk remove users or devices from flag's variant. Limited to 100 per request.

Path variables

Name
Description
id Required. String. Flag's ID.
variantKey Required. String. The variant's key.

Request body

Name
Requirement Type Description
users Required object Contains an string array of user or device ids.

Response

A successful request returns a 200 OK response and OK text.

Request

1curl --request DELETE \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/variants/<variantKey>/bulk-delete-users' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>' \
5 --data '{"users":<["id1", "id2", "id3"]>}'

List deployments

1GET https://experiment.amplitude.com/api/1/flags/{id}/deployments

List all deployments for a flag.

Path variables

Name
Description
id Required. String. Flag's ID.

Response

A successful request returns a 200 OK response and an array of JSON objects with flag's deployment details.

1curl --request GET \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/deployments' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'

1[
2 {
3 "id": <id>,
4 "projectId": <projectId>,
5 "label": "rest-api",
6 "key": <key>,
7 "deleted": false
8 }
9]

Create deployment

1POST https://experiment.amplitude.com/api/1/flags/{id}/deployments

Add a deployment for a flag.

Path variables

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

Request body

Name
Requirement Type Description
deployments Required object Contains an string array of deployment ids.

Example request

1{
2 "deployments": [<deploymentId>]
3}

???example "Example request (click to open)"

Response

A successful request returns a 200 OK response and OK text.

Request

1curl --request POST \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/deployments' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'
5 --data '{"deployments":[<deploymentId>]}'

Remove deployment

1DELETE https://experiment.amplitude.com/api/1/flags/{id}/deployments/{deploymentId}

Remove a deployment from a flag.

Path variables

Name Description
id Required. String. Flag's ID.
deploymentId Required. String. The deployment's ID.

Response

A successful request returns a 200 OK response and OK text.

Request

1curl --request DELETE \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>/deployments/<deploymentId>' \
3 --header 'Accept: application/json' \
4 --header 'Authorization: Bearer <management-api-key>'

Edit

1PATCH https://experiment.amplitude.com/api/1/flags/{id}

Edit a flag.

Path variables

Name Description
id Required. String. Flag's ID.

Request body

Name
Requirement Type Description
name Optional string Name.
description Optional string Description.
bucketingKey Optional string The user property to bucket the user by.
bucketingSalt Optional string Bucketing salt.
bucketingUnit Optional string Bucketing unit represented by a group type from the accounts add-on. Used for group level bucketing and analysis.
evaluationMode Optional string Evaluation mode for the flag, either local or remote.
rolloutPercentage Optional number Rollout percentage for non-targeted users. Range 0 - 100.
targetSegments Optional object See the targetSegments table for more information. When targetSegments object is provided, it will replace existing target segments. Note: cohorts are not supported at the moment.
enabled Optional boolean Property to activate or deactivate flag.
archive Optional boolean Property to archive or unarchive flag.
tags Optional string array A list of tags for the flag. Tags are added and deleted by the same operation. If you would like to add new tags to the existing ones, you should fetch a list of all flag tags first.

Example request

1{
2 "name": "updated name",
3 "description": "updated description",
4 "bucketingKey": "amplitude_id",
5 "bucketingSalt": "<bucketingSalt>",
6 "bucketingUnit": "org id",
7 "evaluationMode": "remote",
8 "rolloutPercentage": 0,
9 "enabled": false,
10 "tags": ["prod", "staging"]
11}

Response

A successful request returns a 200 OK response.

response

1curl --request PATCH \
2 --url 'https://experiment.amplitude.com/api/1/flags/<id>' \
3 --header 'Content-Type: application/json' \
4 --header 'Accept: application/json' \
5 --header 'Authorization: Bearer <management-api-key>' \
6 --data '{"enabled":<enabled>,"rolloutPercentage":<rolloutPercentage>}'

Create

1POST https://experiment.amplitude.com/api/1/flags

Create a new flag.

Request body

Name
Requirement Type Description
projectId Required string The project's ID.
key Required string The flag key.
name Optional string The flag name.
description Optional string Description for the flag.
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. For example: { "control": 1, "treatment": 1 }.
targetSegments Optional object See the targetSegments table for more information.
deployments Optional string array Array of deployments that the flag should be assigned to.
evaluationMode Optional string Experiment evaluation mode; options include remote or local.

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 Required string The segment name.
conditions Required object array Array of conditions.
percentage Required number The allocation percentage for users who match a condition.
rolloutWeights Required object A map from variant key to rollout weight. For example: { "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. Prefix custom and free-form properties with gp:
op Required string The operation to use in this condition.
values Required string array The values to use in the operation.

op

A 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
  • set is
  • set is not
  • set contains
  • set does not contain
  • glob match
  • glob does not match

Example request

1{
2 "projectId":"<projectId>",
3 "name": "Analyze button clicks",
4 "key": "analyze-button-clicks",
5 "description": "analyze button clicks on the main page",
6 "variants": [
7 {
8 "key": "on"
9 }
10 ],
11 "rolloutWeights": {"on": 1},
12 "targetSegments": [
13 {
14 "name": "Segment 1",
15 "conditions": [
16 {
17 "prop": "country",
18 "op": "is",
19 "type": "property",
20 "values": [
21 "United States"
22 ]
23 }
24 ],
25 "percentage": 0,
26 "bucketingKey": "amplitude_id",
27 "rolloutWeights": {
28 "on": 1
29 }
30 }
31 ],
32 "deployments": ["<deploymentId>"],
33 "evaluationMode": "remote"
34}

Response

A successful request returns a 200 OK response and a JSON object with the flag's id and url.

1curl --request POST \
2 --url 'https://experiment.amplitude.com/api/1/flags' \
3 --header 'Content-Type: application/json' \
4 --header 'Accept: application/json' \
5 --header 'Authorization: Bearer <management-api-key>' \
6 --data '{"projectId":"<projectId>","key":"<key>"}'

1{
2 "id": "<id>",
3 "url": "http://experiment.amplitude.com/amplitude/<projectId>/config/<id>"
4}

Was this page helpful?

Thanks for your feedback!

June 4th, 2024

Need help? Contact Support

Visit Amplitude.com

Have a look at the Amplitude Blog

Learn more at Amplitude Academy

© 2024 Amplitude, Inc. All rights reserved. Amplitude is a registered trademark of Amplitude, Inc.