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. |
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.
Name | Description |
---|---|
limit |
The max number of flags to be returned. Capped at 1000. |
cursor |
The offset to start the "page" of results from. |
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": 127 },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": 143 }44 }45 ]46 }47 ],48 "nextCursor": <cursorId>49}
1GET https://experiment.amplitude.com/api/1/flags/<id>
Fetch the configuration details of a flag.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
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": 121 },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": 139 }40 }41 ],42 "deleted": false43}
1GET https://experiment.amplitude.com/api/1/flags/{id}/versions
Fetch a list of all versions for a flag.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
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": 1120 },121 "targetSegments": []122 }123 }124]
1GET https://experiment.amplitude.com/api/1/flags/{id}/versions/{versionId}
Fetch details of a specific version of a flag.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
versionId |
Required. String. The version's ID. |
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": 125 },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": 143 }44 }45 ]46 }47}
1GET https://experiment.amplitude.com/api/1/flags/{id}/variants
Fetch a list of all variants for a flag.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
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": 18 }9]
1GET https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}
Fetch details of a specific variant of a flag.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
variantKey |
Required. String. The variant's key. |
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": 17}
1GET https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}/users
Fetch a list of inclusions for a specific variant of a flag.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
variantKey |
Required. String. The variant's key. |
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]
1POST https://experiment.amplitude.com/api/1/flags/{id}/variants
Create a new variant for a flag
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
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 | string | Optional payload. Value must be a valid JSON element. |
rolloutWeight |
Optional | number | Rollout weight for non-targeted users. |
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": 07}
A successful request returns a 200 OK
response and OK
text.
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>}'
1POST https://experiment.amplitude.com/api/1/flags/<id>/variants/<variantKey>
Edit a variant for a flag.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
variantKey |
Required. String. The variant's key. |
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": 07}
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. |
A successful request returns a 200 OK
response and OK
text.
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>}'
1DELETE https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}
Remove a variant from a flag.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
variantKey |
Required. String. The variant's key. |
A successful request returns a 200 OK
response and OK
text.
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>'
1POST https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}/users
Add inclusions (users or devices) to flag's variant.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
variantKey |
Required. String. The variant's key. |
Name |
Requirement | Type | Description |
---|---|---|---|
inclusions |
Required | object | Contains an string array of user or device ids. |
1{2 "inclusions": ["<user1>@<your-company-email>, <user2>@<your-company-email>, <userId>"]3}
A successful request returns a 200 OK
response and OK
text.
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"]>}'
1DELETE https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}/users/{userIndex}
Remove inclusions (users or devices) from flag's variant.
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 |
A successful request returns a 200 OK
response and OK
text.
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>'
1DELETE https://experiment.amplitude.com/api/1/flags/{id}/variants/{variantKey}/users
Remove all inclusions (users or devices) from flag's variant.
Name |
Description |
---|---|
id |
Required. String. Flag's ID. |
variantKey |
Required. String. The variant's key. |
A successful request returns a 200 OK
response and OK
text.
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>'
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.
Name |
Description |
---|---|
id |
Required. String. Flag's ID. |
variantKey |
Required. String. The variant's key. |
Name |
Requirement | Type | Description |
---|---|---|---|
users |
Required | object | Contains an string array of user or device ids. |
A successful request returns a 200 OK
response and OK
text.
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"]>}'
1GET https://experiment.amplitude.com/api/1/flags/{id}/deployments
List all deployments for a flag.
Name |
Description |
---|---|
id |
Required. String. Flag's ID. |
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": false8 }9]
1POST https://experiment.amplitude.com/api/1/flags/{id}/deployments
Add a deployment for a flag.
Name | Description |
---|---|
id |
Required. String. The object's ID. |
Name |
Requirement | Type | Description |
---|---|---|---|
deployments |
Required | object | Contains an string array of deployment ids. |
1{2 "deployments": [<deploymentId>]3}
???example "Example request (click to open)"
A successful request returns a 200 OK
response and OK
text.
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>]}'
1DELETE https://experiment.amplitude.com/api/1/flags/{id}/deployments/{deploymentId}
Remove a deployment from a flag.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
deploymentId |
Required. String. The deployment's ID. |
A successful request returns a 200 OK
response and OK
text.
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>'
1PATCH https://experiment.amplitude.com/api/1/flags/{id}
Edit a flag.
Name | Description |
---|---|
id |
Required. String. Flag's ID. |
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. |
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}
A successful request returns a 200 OK
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>}'
1POST https://experiment.amplitude.com/api/1/flags
Create a new flag.
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
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": 129 }30 }31 ],32 "deployments": ["<deploymentId>"],33 "evaluationMode": "remote"34}
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}
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.