Patch experiment
Update an experiment. Updating an experiment uses the semantic patch format.
To make a semantic patch request, you must append `domain-model=launchdarkly.semanticpatch` to your `Content-Type` header. To learn more, read [Updates using semantic patch](https://launchdarkly.com/docs/api#updates-using-semantic-patch).
### Instructions
Semantic patch requests support the following `kind` instructions for updating experiments.
#### updateName
> **Deprecated**: `updateName` will be removed in a future version. Use `updateExperimentFields` instead.
Updates the experiment name.
##### Parameters
- `value`: The new name.
Here's an example:
```json
{
"instructions": [{
"kind": "updateName",
"value": "Example updated experiment name"
}]
}
```
#### updateDescription
> **Deprecated**: `updateDescription` will be removed in a future version. Use `updateExperimentFields` instead.
Updates the experiment description.
##### Parameters
- `value`: The new description.
Here's an example:
```json
{
"instructions": [{
"kind": "updateDescription",
"value": "Example updated description"
}]
}
```
#### updateExperimentFields
Updates one or more fields on an experiment or its current iteration. Each field update specifies an operation (`add`, `update`, or `remove`) and an optional value.
Which fields are mutable depends on the current iteration status. To discover which fields and operations are allowed, expand `mutableFieldsByStatus` on the [Get experiment](https://launchdarkly.com/docs/api/experiments/get-experiment) response.
##### Parameters
- `value`: An object mapping field names to field updates. Each field update has the following properties:
- `operation`: The operation to perform. One of `add`, `update`, or `remove`.
- `value`: The new value for the field. Required for `add` and `update` operations.
To find which fields are supported and which operations are allowed for each iteration status, expand `mutableFieldsByStatus` on the [Get experiment](https://launchdarkly.com/docs/api/experiments/get-experiment) response.
Here's an example:
```json
{
"instructions": [{
"kind": "updateExperimentFields",
"value": {
"name": {
"operation": "update",
"value": "Updated experiment name"
},
"tags": {
"operation": "add",
"value": ["tag1", "tag2"]
}
}
}]
}
```
#### saveAndStartNewIteration
Stops the current running iteration, creates a new iteration from it, optionally applies field updates, and starts the new iteration. This is a convenience instruction that combines stopping, updating, and starting in a single operation.
##### Parameters
- `changeJustification`: (Optional) The reason for stopping and starting a new iteration.
- `value`: (Optional) An object mapping field names to field updates, using the same format as `updateExperimentFields`. These updates are applied to the new iteration before it is started.
Here's an example:
```json
{
"instructions": [{
"kind": "saveAndStartNewIteration",
"changeJustification": "Adjusting hypothesis based on early results",
"value": {
"hypothesis": {
"operation": "update",
"value": "Updated hypothesis text"
}
}
}]
}
```
#### startIteration
Starts a new iteration for this experiment. You must [create a new iteration](https://launchdarkly.com/docs/api/experiments/create-iteration) before calling this instruction.
An iteration may not be started until it meets the following criteria:
* Its associated flag is toggled on and is not archived
* Its `randomizationUnit` is set
* At least one of its `treatments` has a non-zero `allocationPercent`
##### Parameters
- `changeJustification`: The reason for starting a new iteration. Required when you call `startIteration` on an already running experiment, otherwise optional.
Here's an example:
```json
{
"instructions": [{
"kind": "startIteration",
"changeJustification": "It's time to start a new iteration"
}]
}
```
#### stopIteration
Stops the current iteration for this experiment.
##### Parameters
- `winningTreatmentId`: The ID of the winning treatment. Treatment IDs are returned as part of the [Get experiment](https://launchdarkly.com/docs/api/experiments/get-experiment) response. They are the `_id` of each element in the `treatments` array.
- `winningReason`: The reason for the winner
Here's an example:
```json
{
"instructions": [{
"kind": "stopIteration",
"winningTreatmentId": "3a548ec2-72ac-4e59-8518-5c24f5609ccf",
"winningReason": "Example reason to stop the iteration"
}]
}
```
#### archiveExperiment
Archives this experiment. Archived experiments are hidden by default in the LaunchDarkly user interface. You cannot start new iterations for archived experiments.
Here's an example:
```json
{
"instructions": [{ "kind": "archiveExperiment" }]
}
```
#### restoreExperiment
Restores an archived experiment. After restoring an experiment, you can start new iterations for it again.
Here's an example:
```json
{
"instructions": [{ "kind": "restoreExperiment" }]
}
```