# Experiment Management API Flag Endpoints

> For AI agents: a documentation index is available at [/docs/llms.txt](/docs/llms.txt). Append `.md` to any page URL for markdown, or send `Accept: text/markdown`.

| Name | Description |
| --- | --- |
| [List](#list) | List of flags including their configuration details. |
| [Get details](#get-details) | Get the configuration details of a flag. |
| [List versions](#list-versions) | List all versions for a flag. |
| [Get version details](#get-version-details) | Get a specific version for a flag. |
| [List variants](#list-variants) | List all variants for a flag. |
| [Get variant details](#get-variant-details) | Get a specific variant for a flag. |
| [Get variant inclusions](#get-variant-inclusions) | Get all inclusions (users) for a variant. |
| [Get variant cohort inclusions](#get-variant-cohort-inclusions) | Get all cohort inclusions for a variant. |
| [Create variant](#create-variant) | Create a new variant for a flag. |
| [Edit variant](#edit-variant) | Edit a variant for a flag. |
| [Remove variant](#remove-variant) | Remove a variant from a flag. |
| [Add users to variant](#add-users-to-variant) | Add users to flag's variant. |
| [Add cohorts to variant](#add-cohorts-to-variant) | Add cohorts to flag's variant. |
| [Remove users from variant](#remove-users-from-variant) | Remove users from flag's variant. |
| [Remove all users from variant](#remove-all-users-from-variant) | Remove all users from flag's variant. |
| [Bulk remove users from variant](#bulk-remove-users-from-variant) | Bulk remove users from experiment's variant. |
| [Bulk remove cohorts from variant](#bulk-remove-cohorts-from-variant) | Bulk remove cohorts from flag's variant. |
| [List deployments](#list-deployments) | List all deployments for a flag. |
| [Create deployment](#create-deployment) | Add a deployment for a flag. |
| [Remove deployment](#remove-deployment) | Remove a deployment from a flag. |
| [Edit](#edit) | Edit flag. |
| [Create](#create) | Create a new flag. |

> **Note:** 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](https://amplitude.com/docs/apis/experiment/experiment-management-api#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.

#### Request

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

#### Response

```json
{
    "flags": [
        {
            "id": <id>,
            "projectId": <projectId>,
            "deployments": [<deploymentId>],
            "key": "flag-key",
            "name": "flag-name",
            "description": "description",
            "enabled": false,
            "evaluationMode": "remote",
            "bucketingKey": "amplitude_id",
            "bucketingSalt": <bucketingSalt>,
            "bucketingUnit": "User",
            "createdBy": "abc@amplitude.com",
            "lastModifiedBy": "abc@amplitude.com",
            "createdAt":"2022-09-09T15:29:47.940Z",
            "lastModifiedAt":"2023-01-25T11:43:41.073Z",
            "variants": [
                {
                    "key": "on"
                }
            ],
            "rolloutPercentage": 0,
            "rolloutWeights": {
                "on": 1
            },
            "targetSegments": [
                {
                    "name": "Segment 1",
                    "conditions": [
                        {
                            "prop": "city",
                            "op": "is",
                            "type": "property",
                            "values": []
                        }
                    ],
                    "percentage": 0,
                    "bucketingKey": "amplitude_id",
                    "rolloutWeights": {
                        "on": 1
                    }
                }
            ],
            "parentDependencies": {
                "flags": {
                    "12345": [
                        "on"
                    ]
                },
                "operator": "all"
            }
        }
    ],
    "nextCursor": <cursorId>
}
```

## 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.

#### Request

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

#### Response

```json
{
    "id": <id>,
    "projectId": <projectId>,
    "deployments": [<deploymentId>],
    "key": "flag-key",
    "name": "flag-key",
    "description": "feature flag access",
    "enabled": true,
    "evaluationMode": "remote",
    "bucketingKey": "amplitude_id",
    "bucketingSalt": "mHdQDzeE",
    "bucketingUnit": "User",
    "variants": [
        {
            "key": "on"
        }
    ],
    "rolloutPercentage": 0,
    "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
            }
        }
    ],
    "parentDependencies": {
        "flags": {
            "12345": [
                "on"
            ]
        },
        "operator": "all"
    },
    "deleted": false
}
```

## 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.

#### Request

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

#### Response

```json
[
    {
        "createdAt": "2023-07-29T03:32:49.594Z",
        "createdBy": <userId>,
        "version": 3,
        "flagConfig": {
            "id": <id>,
            "projectId": <projectId>,
            "deployments": [<deploymentId>],
            "key": "flag-key",
            "name": "flag-key",
            "description": "feature flag access",
            "enabled": true,
            "evaluationMode": "remote",
            "bucketingKey": "amplitude_id",
            "bucketingSalt": "mHdQDzeE",
            "bucketingUnit": "User",
            "variants": [
                {
                    "key": "on"
                }
            ],
            "rolloutPercentage": 0,
            "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
                    }
                }
            ]
        }
    },
    {
        "createdAt": "2023-07-29T03:32:39.494Z",
        "createdBy": <userId>,
        "version": 2,
        "flagConfig": {
            "id": <id>,
            "projectId": <projectId>,
            "deployments": [<deploymentId>],
            "key": "flag-key",
            "name": "flag-key",
            "description": "feature flag access",
            "enabled": false,
            "evaluationMode": "remote",
            "bucketingKey": "amplitude_id",
            "bucketingSalt": "mHdQDzeE",
            "bucketingUnit": "User",
            "variants": [
                {
                    "key": "on"
                }
            ],
            "rolloutPercentage": 0,
            "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
                    }
                }
            ]
        }
    },
    {
        "createdAt": "2023-07-29T03:30:45.703Z",
        "createdBy": <userId>,
        "version": 1,
        "flagConfig": {
            "id": <id>,
            "projectId": <projectId>,
            "deployments": [],
            "key": "flag-key",
            "name": "flag-key",
            "description": "",
            "enabled": false,
            "evaluationMode": "remote",
            "bucketingKey": "amplitude_id",
            "bucketingSalt": "mHdQDzeE",
            "bucketingUnit": "User",
            "variants": [
                {
                    "key": "on"
                }
            ],
            "rolloutPercentage": 0,
            "rolloutWeights": {
                "on": 1
            },
            "targetSegments": []
        }
    }
]
```

## 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.

#### Request

```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>'
```

#### Response

```json
{
    "createdAt": "2023-07-29T03:32:49.594Z",
    "createdBy": <userId>,
    "version": 3,
    "flagConfig": {
        "id": <id>,
        "projectId": <projectId>,
        "deployments": [<deploymentId>],
        "key": "flag-key",
        "name": "flag-key",
        "description": "feature flag access",
        "enabled": true,
        "evaluationMode": "remote",
        "bucketingKey": "amplitude_id",
        "bucketingSalt": "mHdQDzeE",
        "bucketingUnit": "User",
        "variants": [
            {
                "key": "on"
            }
        ],
        "rolloutPercentage": 0,
        "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
                }
            }
        ]
    }
}
```

## 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.

#### Request

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

#### Response

```json
[
  {
    "key": "on",
    "name": "",
    "payload": {},
    "description": "",
    "rolloutWeight": 1
  }
]
```

## 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.

#### Request

```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>'
```

#### Response

```bash
{
    "key": "on",
    "name": "",
    "payload": {},
    "description": "",
    "rolloutWeight": 1
}
```

## 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.

#### Request

```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>'
```

#### Response

```bash
[
    <user>@<your-company-email>,
    <userId>
]
```

## 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.

#### Request

```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>'
```

#### Response

```json
["cohort-id-1", "cohort-id-2"]
```

## 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:** 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.

> **Example:** 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:** 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.

> **Example:** 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.

> **Example:** 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
```

> **Note:**
>
> 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:** 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.

> **Example:** 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:** Example request
>
> ```json
> {
>   "inclusions": ["cohort-id-1", "cohort-id-2"]
> }
> ```

### Response

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

> **Example:** 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](#get-variant-inclusions) |

### Response

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

> **Example:** 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.

> **Example:** 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.

> **Example:** 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.

> **Example:** 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.

#### Request

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

#### Response

```json
[
    {
        "id": <id>,
        "projectId": <projectId>,
        "label": "rest-api",
        "key": <key>,
        "deleted": false
    }
]
```

## 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:** Example request
>
> ```json
> {
>     "deployments": [<deploymentId>]
> }
> ```

### Response

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

> **Example:** 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.

> **Example:** 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`](#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:** 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.

> **Example:** 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`](#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`](#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`](#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](#op) 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`
- `version less than`
- `version less than or equal to`
- `version greater than`
- `version greater than or equal to`

> **Example:** 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.

#### Request

```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>"}'
```

#### Response

```json
{
  "id": "<id>",
  "url": "http://experiment.amplitude.com/amplitude/<projectId>/config/<id>"
}
```