| Name | Description | | --------------------------------------------------------------------- | ---------------------------------------------------------- | | [List](#list) | List of experiments including their configuration details. | | [Get details](#get-details) | Get the configuration details of an experiment. | | [List versions](#list-versions) | List all versions for an experiment. | | [Get version details](#get-version-details) | Get a specific version for an experiment. | | [List variants](#list-variants) | List all variants for an experiment. | | [Get variant details](#get-variant-details) | Get a specific variant for an experiment. | | [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 an experiment. | | [Edit variant](#edit-variant) | Edit a variant for an experiment. | | [Remove variant](#remove-variant) | Remove a variant from an experiment. | | [Add users to variant](#add-users-to-variant) | Add users to experiment's variant. | | [Add cohorts to variant](#add-cohorts-to-variant) | Add cohorts to experiment's variant. | | [Remove users from variant](#remove-users-from-variant) | Remove users from experiment's variant. | | [Remove all users from variant](#remove-all-users-from-variant) | Remove all users from experiment'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 experiment's variant. | | [List deployments](#list-deployments) | List all deployments for an experiment. | | [Add deployment](#create-deployment) | Add a deployment to an experiment. | | [Remove deployment](#remove-deployment) | Remove a deployment from an experiment. | | [Edit](#edit) | Edit experiment. | | [Create](#create) | Create a new experiment. | {% callout type="note" heading="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](/docs/apis/experiment/experiment-management-api#regions). {% /callout %} ## List ```bash GET https://experiment.amplitude.com/api/1/experiments ``` Fetch a list of experiments and their configuration details. Results are ordered with the most recently created items first. ### Query parameters | Name | Description | | ----------------- | ----------------------------------------------------------------------------------------------------------------------------------- | | `key` | Filter experiments whose experiment key matches this value. | | `projectId` | Filter experiments that belong to this project. | | `limit` | The maximum number of experiments to return. Capped at 1000. | | `cursor` | The offset to start the "page" of results from. | | `includeArchived` | Optional. Boolean. Default is false. When false, return only active experiments. When true, return active and archived experiments. | ### Response A successful request returns a `200 OK` response and a list of experiments encoded as JSON in the response body. `createdAt` and `lastModifiedAt` are in UTC in ISO 8601 format. {% code-group %} ```bash Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/experiments?limit=1000' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```json Response { "experiments": [ { "id": , "projectId": , "deployments": [], "key": "experiment-key", "name": "experiment-name", "decision": null, "decisionReason": null, "description": "description", "enabled": true, "evaluationMode": "remote", "bucketingKey": "amplitude_id", "bucketingSalt": , "bucketingUnit": "User", "variants": [ { "key": "control" }, { "key": "treatment" } ], "rolledOutVariant": null, "rolloutPercentage": 10, "rolloutWeights": { "control": 1, "treatment": 1 }, "targetSegments": [ { "name": "Segment 1", "conditions": [ { "prop": "device_id", "op": "is", "type": "property", "values": [ "(none)" ] } ], "percentage": 50, "bucketingKey": "amplitude_id", "rolloutWeights": { "control": 1, "treatment": 1 } } ], "parentDependencies": { "flags": { "12345": [ "slot-1" ] }, "operator": "all" }, "stickyBucketing": false, "state": "planning", "startDate": null, "endDate": null, "experimentType": "a-b-test", "createdBy": "abc@amplitude.com", "lastModifiedBy": "abc@amplitude.com", "createdAt":"2022-09-09T15:29:47.940Z", "lastModifiedAt":"2023-01-25T11:43:41.073Z" }, "nextCursor": ] } ``` {% /code-group %} ## Get details ```bash GET https://experiment.amplitude.com/api/1/experiments/ ``` Fetch the configuration details of an experiment. ### Path variables | Name | Description | | ---- | ----------------------------------------------------------------------------------------------------- | | `id` | Required. String. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | ### Response A successful request returns a `200 OK` response and a JSON object with the experiment's details. {% code-group %} ```bash Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/experiments/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```bash Response { "id": , "projectId": , "deployments": [], "key": "experiment-key", "name": "experiment-key", "decision": null, "decisionReason": null, "description": "save button color", "enabled": true, "evaluationMode": "remote", "bucketingKey": "amplitude_id", "bucketingSalt": , "bucketingUnit": "User", "variants": [ { "key": "control" }, { "key": "treatment" } ], "rolledOutVariant": null, "rolloutPercentage": 0, "rolloutWeights": { "control": 1, "treatment": 1 }, "targetSegments": [ { "name": "Segment 1", "conditions": [ { "prop": "city", "op": "is", "type": "property", "values": [ "San Francisco" ] } ], "percentage": 0, "bucketingKey": "amplitude_id", "rolloutWeights": { "control": 1, "treatment": 1 } } ], "parentDependencies": { "flags": { "12345": [ "slot-1" ] }, "operator": "all" }, "stickyBucketing": false, "state": "running", "startDate": "2023-07-29", "endDate": null, "experimentType": "a-b-test", "deleted": false, "tags": [], "createdBy": "x@amplitude.com" } ``` {% /code-group %} ## List versions ```bash GET https://experiment.amplitude.com/api/1/experiments/{id}/versions ``` Fetch a list of all versions for an experiment. ### Path variables | Name | Description | | ---- | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | ### Response A successful request returns a `200 OK` response and a list of the experiment's versions encoded as an array of JSON objects in the response body. Versions are sorted in descending order. {% code-group %} ```bash Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/experiments//versions' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```json Response [ { "createdAt": "2023-07-29T03:30:18.427Z", "createdBy": , "version": 3, "flagConfig": { "id": , "projectId": , "deployments": [], "key": "experiment-key", "name": "experiment-key", "description": "save button color", "enabled": true, "bucketingKey": "amplitude_id", "variants": [ { "key": "control" }, { "key": "treatment" } ], "rolloutWeights": { "control": 1, "treatment": 1 }, "targetSegments": [ { "name": "Segment 1", "conditions": [ { "prop": "city", "op": "is", "type": "property", "values": [ "San Francisco" ] } ], "percentage": 0, "bucketingKey": "amplitude_id", "rolloutWeights": { "control": 1, "treatment": 1 } } ], "stickyBucketing": false, "startDate": "2023-07-29", "endDate": "2023-07-29", "experimentType": "a-b-test" } }, { "createdAt": "2023-07-29T03:26:23.603Z", "createdBy": , "version": 2, "flagConfig": { "id": , "projectId": , "deployments": [], "key": "experiment-key", "name": "experiment-key", "description": "save button color", "enabled": false, "bucketingKey": "amplitude_id", "variants": [ { "key": "control" }, { "key": "treatment" } ], "rolloutWeights": { "control": 1, "treatment": 1 }, "targetSegments": [], "stickyBucketing": false, "startDate": null, "endDate": null, "experimentType": "a-b-test" } }, { "createdAt": "2023-07-29T03:25:42.236Z", "createdBy": , "version": 1, "flagConfig": { "id": , "projectId": , "deployments": [], "key": "experiment-key", "name": "experiment-key", "description": "", "enabled": false, "bucketingKey": "amplitude_id", "variants": [ { "key": "control" }, { "key": "treatment" } ], "rolloutWeights": { "control": 1, "treatment": 1 }, "targetSegments": [], "stickyBucketing": false, "startDate": null, "endDate": null, "experimentType": "a-b-test" } } ] ``` {% /code-group %} ## Get version details ```bash GET https://experiment.amplitude.com/api/1/experiments/{id}/versions/{versionId} ``` Fetch details of a specific version of an experiment. ### Path variables | Name | Description | | ----------- | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment 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. {% code-group %} ```curl Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/experiments//versions/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```json Response { "createdAt": "2023-07-29T03:30:18.427Z", "createdBy": , "version": 3, "flagConfig": { "id": , "projectId": , "deployments": [], "key": "experiment-key", "name": "experiment-key", "description": "save button color", "enabled": true, "bucketingKey": "amplitude_id", "variants": [ { "key": "control" }, { "key": "treatment" } ], "rolloutWeights": { "control": 1, "treatment": 1 }, "targetSegments": [ { "name": "Segment 1", "conditions": [ { "prop": "city", "op": "is", "type": "property", "values": [ "San Francisco" ] } ], "percentage": 0, "bucketingKey": "amplitude_id", "rolloutWeights": { "control": 1, "treatment": 1 } } ], "stickyBucketing": false, "startDate": "2023-07-29", "endDate": "2023-07-29", "experimentType": "a-b-test" } } ``` {% /code-group %} ## List variants ```bash GET https://experiment.amplitude.com/api/1/experiments/{id}/variants ``` Fetch a list of all variants for an experiment. ### Path variables | Name | Description | | ---- | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | ### 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. {% code-group %} ```bash Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/experiments//variants' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```json Response [ { "key": "control", "name": "", "payload": {}, "description": "", "rolloutWeight": 1 }, { "key": "treatment", "name": "", "payload": {}, "description": "", "rolloutWeight": 1 } ] ``` {% /code-group %} ## Get variant details ```bash GET https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey} ``` Fetch details of a specific variant of an experiment. ### Path variables | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment 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 the experiment variant. {% code-group %} ```bash Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/experiments//variants/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```bash Response { "key": "control", "name": "", "payload": {}, "description": "", "rolloutWeight": 1 } ``` {% /code-group %} ## Get variant inclusions ```bash GET https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/users ``` Fetch a list of inclusions for a specific variant of an experiment. ### Path variables | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | | `variantKey` | Required. Type: `string`. The variant's key. | ### Response A successful request returns a `200 OK` response and a list of inclusions for the experiment's variant as an array of JSON objects. {% code-group %} ```bash Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/experiments//variants//users' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```bash Response [ @, ] ``` {% /code-group %} ## Get variant cohort inclusions ```bash GET https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/cohorts ``` Fetch a list of cohort inclusions for a specific variant of an experiment. ### Path variables | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | | `variantKey` | Required. Type: `string`. The variant's key. | ### Response A successful request returns a `200 OK` response and a list of cohort inclusions for the experiment's variant as an array of cohort IDs. {% code-group %} ```bash Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/experiments//variants//cohorts' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```json Response ["cohort-id-1", "cohort-id-2"] ``` {% /code-group %} ## Create variant ```bash POST https://experiment.amplitude.com/api/1/experiments/{id}/variants ``` Create a new variant for an experiment. ### Path variables | Name | Description | | ---- | ----------------------------------------------------------------------------------------------------- | | `id` | Required. String. The experiment's ID. Find the ID in the URL of the experiment 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. | | `rolloutWeight` | Optional. Type: `number`. Rollout weight for non-targeted users. | {% callout type="example" heading="Request" %} ```json { "key": "new-variant-key", "description": "optional description for variant", "name": "optional name for variant", "payload": { "variant-payload": "example payload" }, "rolloutWeight": 0 } ``` {% /callout %} ### Response A successful request returns a `200 OK` response and `OK` text. {% callout type="example" heading="Example request" %} ```bash curl --request POST \ --url 'https://experiment.amplitude.com/api/1/experiments//variants' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"key":"","name":"","description":"","payload":"","rolloutWeight":}' ``` {% /callout %} ## Edit variant ```bash PATCH https://experiment.amplitude.com/api/1/experiments//variants/ ``` Edit a variant for an experiment. ### Path variables | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | | `variantKey` | Required. Type: `string`. The variant's key. | ### 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. This value replaces the existing value for the variant payload. | | `rolloutWeight` | Optional. Type: `number`. Rollout weight for non-targeted users. | {% callout type="example" heading="Example request" %} ```json { "key": "updated-variant-key", "description": "updated-optional description for variant", "name": "optional name for variant", "payload": { "variant-payload": "example payload" }, "rolloutWeight": 10 } ``` {% /callout %} ### Response A successful request returns a `200 OK` response and `OK` text. {% callout type="example" heading="Request" %} ```curl curl --request PATCH \ --url 'https://experiment.amplitude.com/api/1/experiments//variants/' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"key":"","name":"","description":"","payload":"","rolloutWeight":}' ``` {% /callout %} ## Remove variant ```bash DELETE https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey} ``` Remove a variant from an experiment. ### Path variables | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | | `variantKey` | Required. Type: `string`. The variant's key. | ### Response A successful request returns a `200 OK` response and `OK` text. {% callout type="example" heading="Request" %} ```curl curl --request DELETE \ --url 'https://experiment.amplitude.com/api/1/experiments//variants/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` {% /callout %} ## Add users to variant ```bash POST https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/users ``` Add inclusions (users or devices) to the experiment's variant. ### Path variables | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | | `variantKey` | Required. Type: `string`. The variant's key. | {% callout type="example" heading="Example request" %} ```bash { "inclusions": [@, @, ] } ``` {% /callout %} ### Request body | Name | Description | | ------------ | ------------------------------------------------------------------------ | | `inclusions` | Required. Type: `object`. Contains a string array of user or device IDs. | ### Response A successful request returns a `200 OK` response and `OK` text. {% callout type="example" heading="Request" %} ```curl curl --request POST \ --url 'https://experiment.amplitude.com/api/1/experiments//variants//users' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"inclusions":<["id1", "id2", "id3"]>}' ``` {% /callout %} ## Add cohorts to variant ```bash POST https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/cohorts ``` Add cohort inclusions to the experiment's variant. ### Path variables | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment 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. | {% callout type="example" heading="Example request" %} ```json { "inclusions": ["cohort-id-1", "cohort-id-2"] } ``` {% /callout %} ### Response A successful request returns a `200 OK` response and `OK` text. {% callout type="example" heading="Request" %} ```bash curl --request POST \ --url 'https://experiment.amplitude.com/api/1/experiments//variants//cohorts' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"inclusions":["cohort-id-1", "cohort-id-2"]}' ``` {% /callout %} ## Remove users from variant ```bash DELETE https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/users/{userIndex} ``` Remove inclusions (users or devices) from the experiment's variant. ### Path variables | Name | Description | | ------------ | --------------------------------------------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment 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. {% callout type="example" heading="Request" %} ```curl curl --request DELETE \ --url 'https://experiment.amplitude.com/api/1/experiments//variants//users/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` {% /callout %} ## Remove all users from variant ```bash DELETE https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/users ``` Remove all inclusions (users or devices) from the experiment's variant. ### Path variables | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | | `variantKey` | Required. Type: `string`. The variant's key. | ### Response A successful request returns a `200 OK` response and `OK` text. {% callout type="example" heading="Request" %} ```curl curl --request DELETE \ --url 'https://experiment.amplitude.com/api/1/experiments//variants//users' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` {% /callout %} ## Bulk remove users from variant ```bash DELETE https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/bulk-delete-users ``` Bulk remove users or devices from the experiment's variant. Limited to 100 per request. ### Path variables | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | | `variantKey` | Required. Type: `string`. The variant's key. | ### Request body | Name | Description | | ------- | ------------------------------------------------------------------------ | | `users` | Required. Type: `object`. Contains a string array of user or device IDs. | ### Response A successful request returns a `200 OK` response and `OK` text. {% callout type="example" heading="Request" %} ```curl curl --request DELETE \ --url 'https://experiment.amplitude.com/api/1/experiments//variants//bulk-delete-users' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"users":<["id1", "id2", "id3"]>}' ``` {% /callout %} ## Bulk remove cohorts from variant ```bash DELETE https://experiment.amplitude.com/api/1/experiments/{id}/variants/{variantKey}/bulk-delete-cohorts ``` Bulk remove cohorts from the experiment's variant. Limited to 100 per request. ### Path variables | Name | Description | | ------------ | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment 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. {% callout type="example" heading="Request" %} ```bash curl --request DELETE \ --url 'https://experiment.amplitude.com/api/1/experiments//variants//bulk-delete-cohorts' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"users":["cohort-id-1", "cohort-id-2"]}' ``` {% /callout %} ## List deployments ```bash GET https://experiment.amplitude.com/api/1/experiments/{id}/deployments ``` List all deployments for an experiment. ### Path variables | Name | Description | | ---- | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | ### Response A successful request returns a `200 OK` response and an array of JSON objects with the experiment's deployment details. {% code-group %} ```curl Request curl --request GET \ --url 'https://experiment.amplitude.com/api/1/experiments//deployments' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` ```json Response [ { "id": , "projectId": , "label": "rest-api", "key": , "deleted": false } ] ``` {% /code-group %} ## Add deployment ```bash POST https://experiment.amplitude.com/api/1/experiments/{id}/deployments ``` Add a deployment to an experiment. ### Path variables | Name | Description | | ---- | ----------------------------------------------------------------------------------------------------- | | `id` | Required. String. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | ### Request body | Name | Description | | ------------- | -------------------------------------------------------------------------- | | `deployments` | Required. Type: `string array`. Contains a string array of deployment IDs. | {% callout type="example" heading="Example request" %} ```json { "deployments": [""] } ``` {% /callout %} ### Response A successful request returns a `200 OK` response and `OK` text. {% callout type="example" heading="Request" %} ```curl curl --request POST \ --url 'https://experiment.amplitude.com/api/1/experiments//deployments' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' --data '{"deployments":[]}' ``` {% /callout %} ## Remove deployment ```bash DELETE https://experiment.amplitude.com/api/1/experiments/{id}/deployments/{deploymentId} ``` Remove a deployment from an experiment. ### Path variables | Name | Description | | -------------- | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment in the Amplitude app. | | `deploymentId` | Required. Type: `string`. The deployment's ID. | ### Response A successful request returns a `200 OK` response and `OK` text. {% callout type="example" heading="Request" %} ```bash curl --request DELETE \ --url 'https://experiment.amplitude.com/api/1/experiments//deployments/' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' ``` {% /callout %} ## Edit {% callout type="note" %} Neither Web Experimentation nor Guides and Surveys support editing experiments. Attempts to edit a Web Experimentation or a Guides and Surveys experiment return a `405` error. {% /callout %} ```bash PATCH https://experiment.amplitude.com/api/1/experiments/{id} ``` Edit an experiment. ### Path variables | Name | Description | | ---- | ------------------------------------------------------------------------------------------------------------- | | `id` | Required. Type: `string`. The experiment's ID. Find the ID in the URL of the experiment 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 experiment, 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. The `targetSegments` object array replaces existing target segments. This option doesn't support cohorts. | | `enabled` | Optional. Type: `boolean`. Property to activate or deactivate the experiment. | | `archive` | Optional. Type: `boolean`. Property to archive or unarchive the experiment. | | `experimentType` | Optional. Type: `string`. Experiment type. Options include `a-b-test` or `multi-arm-bandit`. | | `stickyBucketing` | Optional. Type: `boolean`. If true, the experiment uses [sticky bucketing](/docs/feature-experiment/implementation#sticky-bucketing). | | `startDate` | Optional. Type: `string`. Start date of the experiment in ISO 8601 format. | | `endDate` | Optional. Type: `string`. End date of the experiment in ISO 8601 format. End date can be null. | | `exposureEvent` | Optional. Type: `object`. Refer to the [`exposureEvent`](#exposureevent) table for more information. If set to null, Amplitude uses the Amplitude Exposure Event. | | `tags` | Optional. Type: `string array`. A list of tags for the experiment. Tags are added and deleted by the same operation. To add new tags to the existing ones, fetch a list of all experiment tags first. | | `decision` | Optional. Type: `string`. Options include `rollout`, `rollback`, `continue-running`. | | `decisionReason` | Optional. Type: `string`. The reason for the decision. | | `rolledOutVariant` | Optional. Type: `string`. The variant key or name that you rolled out. | #### exposureEvent | Name | Description | | ------------ | -------------------------------------------------------------------------------------------------------------------------- | | `event_type` | Required. Type: `string`. Event type. | | `filters` | Required. Type: `object array`. A list of property filters. Refer to the [`filters`](#filters) table for more information. | #### filters | Name | Description | | --------------- | -------------------------------------------------------------------------------------------------------------------------------------------------- | | `group_type` | Optional. Type: `string`. Group type of the filter; can be null. Can be `User` value or one of the group values, like `org_id`, `org name` | | `subprop_key` | Required. Type: `string`. Filter's key; can be null. | | `subprop_op` | Required. Type: `string`. The [operation](#subprop_op) to use in this filter. | | `subprop_type` | Required. Type: `string`. Either `event`, `user` or `group` indicating that the property is either an event, user or group property, respectively. | | `subprop_value` | Required. Type: `string array`. A list of values to filter the event property by. | #### subprop_op - `is` - `is not` - `contains` - `does not contain` - `less` - `less or equal` - `greater` - `greater or equal` - `glob match` - `glob does not match` {% callout type="example" heading="Example request" %} ```json { "name": "updated name", "description": "updated description", "bucketingKey": "amplitude_id", "bucketingSalt": "", "evaluationMode": "remote", "rolloutPercentage": 0, "enabled": true, "experimentType": "a-b-test", "stickyBucketing": false, "startDate": "2023-07-31T10:26:00.996Z", "endDate": "2023-09-23T10:26:00.996Z", "tags": ["prod", "staging"], "exposureEvent": { "event_type": "_active", "filters": [ { "group_type": "User", "subprop_key": "amplitude_day_of_week", "subprop_op": "is", "subprop_type": "day_time_prop", "subprop_value": ["Tuesday"] } ] } } ``` {% /callout %} ### Response A successful request returns a `200 OK` response. {% callout type="example" heading="Request" %} ```curl curl --request PATCH \ --url 'https://experiment.amplitude.com/api/1/experiments/' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"enabled":,"rolloutPercentage":}' ``` {% /callout %} ## Create ```bash POST https://experiment.amplitude.com/api/1/experiments ``` Create a new feature experiment. ### Request body | Name | Description | | ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | `projectId` | Required. Type: `string`. The project's ID. | | `key` | Required. Type: `string`. The flag key. | | `name` | Optional. Type: `string`. The experiment name. | | `description` | Optional. Type: `string`. Description for the experiment. | | `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 deployment IDs to assign the experiment to. | | `evaluationMode` | Optional. Type: `string`. Experiment evaluation mode. Options include `remote` or `local`. | | `experimentType` | Optional. Type: `string`. Experiment type. Options include `a-b-test` or `multi-arm-bandit`. | #### variants The `variants` field contains these objects. | Name | Description | | ------------- | ---------------------------------------------------------------------------------------------------------------------------------------- | | `key` | Required. Type: `string`. The key (a.k.a 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. | | `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` {% callout type="example" heading="Example request" %} ```json { "projectId": "", "name": "Analyze button clicks experiment", "key": "analyze-button-clicks-experiment", "description": "analyze button clicks on the main page", "variants": [ { "key": "control" }, { "key": "treatment" } ], "rolloutWeights": { "control": 1, "treatment": 1 }, "targetSegments": [ { "name": "Segment 1", "conditions": [ { "prop": "country", "op": "is", "type": "property", "values": ["United States"] } ], "percentage": 0, "bucketingKey": "amplitude_id", "rolloutWeights": { "control": 1, "treatment": 1 } } ], "deployments": [""], "evaluationMode": "remote", "experimentType": "a-b-test" } ``` {% /callout %} ### Response A successful request returns a `200 OK` response and a JSON object with the experiment's id and url. {% code-group %} ```bash Request curl --request POST \ --url 'https://experiment.amplitude.com/api/1/experiments' \ --header 'Content-Type: application/json' \ --header 'Accept: application/json' \ --header 'Authorization: Bearer ' \ --data '{"projectId":"","key":""}' ``` ```json Response { "id": "", "url": "http://experiment.amplitude.com/amplitude//config/" } ``` {% /code-group %}