| Name | Description |
| --- | --- |
| [List](#list) | List of mutex groups including their configuration details. |
| [Edit Mutex Group](#edit-mutex-group) | Edit mutex group. |
| [Edit Mutex Group Slots](#edit-mutex-group-slots) | Edit mutex group slots. |
| [Create](#create) | Create a new mutex. |


## List

```bash
GET https://experiment.amplitude.com/api/1/mutexes
```

Fetch a list of mutex groups including their configuration details.

### Query parameters

| Name| Description |
| --- | --- |
| `limit` | The max number of mutex groups to be returned. Capped at 1000. |
| `cursor` | The offset to start the "page" of results from. |

### Response

A successful request returns a `200 OK` response and a list of mutex groups encoded as JSON in the response body.

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

```json Response
{
    "mutexes": [
        {
            "id": <id>,
            "projectId": <projectId>,
            "name": "mutex name",
            "key": "mutex-key",
            "description": null,
            "evaluationMode": "local",
            "bucketingKey": "device_id",
            "bucketingSalt": <bucketingSalt>,
            "slots": [
                {
                    "name": "SLOT 1",
                    "index": 1,
                    "variantKey": "slot-1",
                    "percentage": 95,
                    "experiments": [
                        123
                    ],
                    "holdouts": [
                        456
                    ],
                    "individuals": [],
                    "cohorts": []
                },
                {
                    "name": "SLOT 2",
                    "index": 2,
                    "variantKey": "slot-2",
                    "percentage": 5,
                    "experiments": [],
                    "holdouts": [],
                    "individuals": [],
                    "cohorts": []
                }
            ]
        }
    ],
    "nextCursor": <cursorId>
}
```
{% /code-group %}

## Get details

```bash
GET https://experiment.amplitude.com/api/1/mutexes/<id>
```

Fetch the configuration details of a mutex group.

### Path variables

| Name | Description |
|---|----|
|`id`| Required. String. Mutex group's ID.|

### Response

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

{% code-group %}
```bash Request
curl --request GET \
    --url 'https://experiment.amplitude.com/api/1/mutexes/<id>' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>'
```

```bash Response
{
    "id": <id>,
    "projectId": <projectId>,
    "name": "mutex name",
    "key": "mutex-key",
    "description": null,
    "evaluationMode": "local",
    "bucketingKey": "device_id",
    "bucketingSalt": <bucketingSalt>,
    "slots": [
        {
            "name": "SLOT 1",
            "index": 1,
            "variantKey": "slot-1",
            "percentage": 95,
            "experiments": [
                123
            ],
            "holdouts": [
                456
            ],
            "individuals": [],
            "cohorts": []
        },
        {
            "name": "SLOT 2",
            "index": 2,
            "variantKey": "slot-2",
            "percentage": 5,
            "experiments": [],
            "holdouts": [],
            "individuals": [],
            "cohorts": []
        }
    ]
}
```
{% /code-group %}

## Edit Mutex Group

```bash
PATCH https://experiment.amplitude.com/api/1/mutexes/{id}
```

Edit a mutex group.

### Path variables

|Name|Description|
|---|----|
|`id`| Required. String. Mutex group's ID.|

### Request body

| Name | Description |
|------|-------------|
| `name` | Optional. Type: `string`. The mutex group name. |
| `description` | Optional. Type: `string`. The mutex group description. |
| `archive` | Optional. Type: `boolean`. Archives or unarchives the mutex group. If true, Amplitude ignores all other arguments, marks the mutex group as deleted, and removes it from all child experiments' parent dependencies. |

{% callout type="example" heading="Example request" %}
```json
{
    "name": "updated name",
    "description": "updated description"
}
```
{% /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/mutexes/<id>' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>' \
    --data '{"name": "updated name"}'
```
{% /callout %}

## Edit Mutex Group Slots

```bash
PATCH https://experiment.amplitude.com/api/1/mutexes/{id}/slots/{slotIndex}
```

Edit a mutex group slot.

### Path variables

|Name|Description|
|---|----|
|`id`| Required. String. Mutex group's ID.|
|`slotIndex`| Required. Number. Slot index of this mutex.|

### Request body

| Name | Description |
|------|-------------|
| `experiments` | Optional. Type: `number array`. List of experiment ids to be included. |
| `holdouts` | Optional. Type: `number array`. List of holdout group ids to be included. |
| `individuals` | Optional. Type: `string array`. List of user ids or device ids to be included. |

{% callout type="example" heading="Example request" %}
```json
{
    "experiments": [123, 456],
    "individuals": ["x@amplitude.com", "y@amplitude.com", "abcde-12345"]
}
```
{% /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/mutexes/<id>/slots/<slotIndex>' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>' \
    --data '{"experiments": [123, 456]}'
```
{% /callout %}

## Create

```bash
POST https://experiment.amplitude.com/api/1/mutexes
```

Create a new mutex group.

### Request body

| Name | Description |
|------|-------------|
| `projectId` | Required. Type: `number`. Project id of the mutex group. |
| `name` | Required. Type: `string`. The mutex group name. |
| `key` | Optional. Type: `string`. The mutex group key. Must be unique across all flags, experiments, holdout groups, and mutex groups. If not specified, Amplitude generates one. |
| `description` | Optional. Type: `string`. Description for the mutex group. |
| `evaluationMode` | Optional. Type: `string`. Mutex group evaluation mode. Options are `local` or `remote`. Defaults to `remote`. |
| `bucketingKey` | Optional. Type: `string`. The user property to bucket the user by. Defaults to `amplitude_id`. |
| `bucketingSalt` | Optional. Type: `string`. Mutex group bucketing salt. Defaults to a randomized string. |
| `slots` | Required. Type: `object array`. Array of [`slots`](#slots). Up to 20 slots. Order matters. |

#### slots

The `slots` field contains these objects.

| Name | Description |
|------|-------------|
| `percentage` | Required. Type: `number`. The percentage of traffic to this slot. An integer between 1 and 100, inclusive. The sum of percentages across all slots must equal 100. |
| `experiments` | Optional. Type: `string array`. List of experiment ids to be included. |
| `holdouts` | Optional. Type: `number array`. List of holdout group id to be included. |
| `individuals` | Optional. Type: `number array`. List of user ids or device ids to be included. |

{% callout type="example" heading="Example request" %}
```json
{
    "projectId":"<projectId>",
    "name": "Example Mutex Group",
    "key": "example-mutex",
    "description": "An example mutex group",
    "evaluationMode": "remote",
  	"slots": [
      	{
      		"percentage": 40,
          	"experiments": [123],
          	"holdouts": [456]
      	},
      	{
      		"percentage": 60,
          	"experiments": [789],
          	"individuals": ["x@amplitude.com"]
      	}
    ]
}
```
{% /callout %}

### Response

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

{% code-group %}
```bash Request
curl --request POST \
    --url 'https://experiment.amplitude.com/api/1/mutexes' \
    --header 'Content-Type: application/json' \
    --header 'Accept: application/json' \
    --header 'Authorization: Bearer <management-api-key>' \
    --data '{"projectId":"<projectId>","slots":[{"percentage":40},{"percentage":60}]}'
```

```json Response
{
    "id": "<id>",
    "url": "http://experiment.amplitude.com/amplitude/experiments/grouped-experiments"
}
```
{% /code-group %}