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.
Get variant cohort inclusions	Get all cohort inclusions 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.
Add cohorts to variant	Add cohorts 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.
Bulk remove cohorts from variant	Bulk remove cohorts from flag'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.

EU data residency

The examples on this page use the default base URL https://experiment.amplitude.com. If your project uses Amplitude's EU data center, use https://experiment.eu.amplitude.com instead. For more information, refer to Regions.

List

bash

GET 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
`key`	Filter flags whose flag key matches this value.
`projectId`	Filter flags that belong to this project.
`limit`	The maximum number of flags to return. Capped at 1000.
`cursor`	The offset to start the page of results from.
`includeArchived`	Filter to include archived flags. Default is `false`.

Response

A successful request returns a 200 OK response and a JSON-encoded list of flags in the response body. createdAt and lastModifiedAt are in UTC in ISO 8601 format.

bash

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

Get details

bash

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

Fetch the configuration details of a flag.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.

Response

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

bash

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

List versions

bash

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

Fetch a list of all versions for a flag.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.

Response

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

bash

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

Get version details

bash

GET 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. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`versionId`	Required. Type: `string`. The version's ID.

Response

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

bash

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

List variants

bash

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

Fetch a list of all variants for a flag.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.

Response

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

bash

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

Get variant details

bash

GET 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. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.

Response

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

bash

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

Get variant inclusions

bash

GET 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. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.

Response

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

bash

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

Get variant cohort inclusions

bash

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

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

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.

Response

A successful request returns a 200 OK response and the variant's cohort inclusions as an array of cohort IDs.

bash

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

Create variant

bash

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

Create a new variant for a flag

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.

Request body

Name	Description
`key`	Required. Type: `string`. The variant key. Can only contain letters, numbers, underscores (`_`), and hyphens (`-`).
`description`	Optional. Type: `string`. Description for the variant.
`name`	Optional. Type: `string`. Name for the variant.
`payload`	Optional. Type: `JSON`. Optional payload. Value must be a valid JSON element, such as an object, string, or number.
`rolloutWeight`	Optional. Type: `number`. Rollout weight for non-targeted users.

Example request

json

{
  "key": "new-variant-key",
  "description": "optional description for variant",
  "name": "optional name for variant",
  "payload": { "variant-payload": "example payload" },
  "rolloutWeight": 0
}

Response

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

Request

bash

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

Edit variant

bash

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

Edit a variant for a flag.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.

Example request

json

{
  "key": "updated-variant-key",
  "description": "updated optional description for variant",
  "name": "optional name for variant",
  "payload": { "variant-payload": "example payload" },
  "rolloutWeight": 0
}

Request body

Name	Description
`key`	Optional. Type: `string`. The variant key. Can only contain letters, numbers, underscores (`_`), and hyphens (`-`).
`description`	Optional. Type: `string`. Description for the variant.
`name`	Optional. Type: `string`. Name for the variant.
`payload`	Optional. Type: `JSON`. Optional payload. Value must be a valid JSON element, such as an object, string, or number. This value replaces the existing value for the variant payload.
`rolloutWeight`	Optional. Type: `number`. Rollout weight for non-targeted users.

Response

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

Request

bash

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

Remove variant

bash

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

Remove a variant from a flag.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.

Response

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

Request

bash

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

Add users to variant

bash

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

You can have up to 2,000 inclusions per variant. If you exceed this limit, Amplitude returns a 400 error.

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

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.

Request body

Name	Description
`inclusions`	Required. Type: `object`. Contains a string array of user or device IDs.

Example request

json

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

Response

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

Request

bash

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

Add cohorts to variant

bash

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

Add cohort inclusions to a flag's variant.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.

Request body

Name	Description
`inclusions`	Required. Type: `array`. An array of cohort IDs to add.

Example request

json

{
  "inclusions": ["cohort-id-1", "cohort-id-2"]
}

Response

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

Request

bash

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

Remove users from variant

bash

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

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

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.
`userIndex`	Required. Type: `string`. The user's index. Zero-indexed. Get an index-based array of users from Get variant inclusions

Response

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

Request

bash

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

Remove all users from variant

bash

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

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

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.

Response

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

Request

bash

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

Bulk remove users from variant

bash

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

Bulk remove users or devices from a flag's variant. Limited to 100 for each request.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.

Request body

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

Response

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

Request

bash

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

Bulk remove cohorts from variant

bash

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

Bulk remove cohorts from a flag's variant. Limited to 100 for each request.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`variantKey`	Required. Type: `string`. The variant's key.

Request body

Name	Description
`users`	Required. Type: `array`. An array of cohort IDs to remove.

Response

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

Request

bash

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

List deployments

bash

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

List all deployments for a flag.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.

Response

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

bash

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

Create deployment

bash

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

Add a deployment for a flag.

Path variables

Name	Description
`id`	Required. Type: `string`. The object's ID.

Request body

Name	Description
`deployments`	Required. Type: `string array`. Contains a string array of deployment IDs.

Example request

json

{
    "deployments": [<deploymentId>]
}

Response

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

Request

bash

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

Remove deployment

bash

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

Remove a deployment from a flag.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.
`deploymentID`	Required. Type: `string`. The deployment's ID.

Response

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

Request

bash

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

Edit

bash

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

Edit a flag.

Path variables

Name	Description
`id`	Required. Type: `string`. The flag's ID. Find the ID in the URL of the flag in the Amplitude app.

Request body

Name	Description
`name`	Optional. Type: `string`. Name.
`description`	Optional. Type: `string`. Description.
`bucketingKey`	Optional. Type: `string`. The user property to bucket the user by.
`bucketingSalt`	Optional. Type: `string`. Bucketing salt.
`bucketingUnit`	Optional. Type: `string`. Bucketing unit represented by a group type from the accounts add-on. Used for group level bucketing and analysis.
`evaluationMode`	Optional. Type: `string`. Evaluation mode for the flag, either `local` or `remote`.
`rolloutPercentage`	Optional. Type: `number`. Rollout percentage for non-targeted users. Range 0 - 100.
`targetSegments`	Optional. Type: `object array`. Refer to the `targetSegments` table for more information. When you provide the `targetSegments` object array, it replaces existing target segments. This option doesn't support cohorts.
`enabled`	Optional. Type: `boolean`. Property to activate or deactivate the flag.
`archive`	Optional. Type: `boolean`. Property to archive or unarchive the flag.
`tags`	Optional. Type: `string array`. A list of tags for the flag. Tags are added and deleted by the same operation. To add new tags to existing ones, fetch a list of all flag tags first.

Example request

json

{
  "name": "updated name",
  "description": "updated description",
  "bucketingKey": "amplitude_id",
  "bucketingSalt": "<bucketingSalt>",
  "bucketingUnit": "org id",
  "evaluationMode": "remote",
  "rolloutPercentage": 0,
  "enabled": false,
  "tags": ["prod", "staging"]
}

Response

A successful request returns a 200 OK response.

response

bash

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

Create

bash

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

Create a new flag.

Request body

Name	Description
`projectId`	Required. Type: `string`. The project's ID.
`key`	Required. Type: `string`. The flag key.
`name`	Optional. Type: `string`. The flag name.
`description`	Optional. Type: `string`. Description for the flag.
`variants`	Optional. Type: `object array`. Array of `variants`.
`bucketingKey`	Optional. Type: `string`. The user property to bucket the user by.
`rolloutWeights`	Optional. Type: `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. Type: `object array`. Refer to the `targetSegments` table for more information.
`deployments`	Optional. Type: `string array`. Array of deployments that the flag should be assigned to.
`evaluationMode`	Optional. Type: `string`. Experiment evaluation mode; options include `remote` or `local`.

`variants`

The variants field contains these objects.

Name	Description
`key`	Required. Type: `string`. The key (also called value) of the variant. Can only contain letters, numbers, underscores (`_`), and hyphens (`-`).
`payload`	Optional. Type: `JSON`. Optional payload. Value must be a valid JSON element, such as an object, string, or number.
`name`	Optional. Type: `string`. The variant name.
`description`	Optional. Type: `string`. The variant description.

`targetSegments`

The targetSegments field contains these objects.

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

`conditions`

The conditions field contains these objects.

Name	Description
`type`	Required. Type: `string`. Must have value: `property`
`prop`	Required. Type: `string`. The property to use in the condition. Prefix custom and free-form properties with `gp:`
`op`	Required. Type: `string`. The operation to use in this condition.
`values`	Required. Type: `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

json

{
  "projectId": "<projectId>",
  "name": "Analyze button clicks",
  "key": "analyze-button-clicks",
  "description": "analyze button clicks on the main page",
  "variants": [
    {
      "key": "on"
    }
  ],
  "rolloutWeights": { "on": 1 },
  "targetSegments": [
    {
      "name": "Segment 1",
      "conditions": [
        {
          "prop": "country",
          "op": "is",
          "type": "property",
          "values": ["United States"]
        }
      ],
      "percentage": 0,
      "bucketingKey": "amplitude_id",
      "rolloutWeights": {
        "on": 1
      }
    }
  ],
  "deployments": ["<deploymentId>"],
  "evaluationMode": "remote"
}

Response

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

bash

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

Was this helpful?