---
title: "Update Experiment"
method: PUT
path: "/api/v1/experiments/{experiment_id}"
tags: ["experiments"]
---

# Update Experiment

`PUT /api/v1/experiments/{experiment_id}`

Update an experiment. Only an experiment in 'draft' status can be updated.

## Path parameters

- `experiment_id` integer, required

## Request body

- ExperimentUpdateRequest — Request model to update an experiment.
  - `name` string, required — The name of the experiment
  - `description` string, nullable — The hypothesis under test
  - `variants` DaoExperimentVariantWrite[] — The variants of the experiment, as a complete set. Two or more, each on a different agent, exactly one of them the control.
    - `name` string, required — The name of the variant, unique within the experiment
    - `weight` integer, required — The percentage of the channel target's traffic this variant answers. The weights of an experiment's variants must add up to 100. (E.g., two variants with a weight of 50 each split the traffic evenly.)
    - `is_control` boolean — Whether this is the reference variant the others are measured against
    - `agent_id` integer, required — The agent this variant runs

## Response `200`

Successful Response

- ExperimentResponse — Response model for experiment operations. An experiment splits the traffic of one channel target between two or more agents, so that the agents can be compared on the same population. One variant is the control the others are measured against. Each variant points at the agent that variant runs and carries the percentage of traffic it answers; the weights of an experiment add up to 100.
  - `id` integer, required — The internal ID of the experiment
  - `name` string, required — The name of the experiment
  - `target_id` integer, nullable, required — The channel target being split, or null if that target has since been deleted. A running experiment always has one.
  - `variants` DaoExperimentVariantDetail[], required — The variants of the experiment, in a stable order
    - `id` integer, required — The internal ID of the variant
    - `name` string, required — The name of the variant, which is the grouping key in reports
    - `weight` integer, required — The percentage of the channel target's traffic this variant answers. The weights of an experiment's variants must add up to 100. (E.g., two variants with a weight of 50 each split the traffic evenly.)
    - `is_control` boolean, required — Whether this is the reference variant the others are measured against
    - `agent_id` integer, required — The agent this variant runs
    - `agent_name` string, required — The name of that agent
  - `description` string, nullable — The hypothesis under test
  - `status` 'draft' | 'running' | 'stopped', required — Status of an experiment. The column is a varchar and not a database enum, so a new value here does not need a migration.
  - `started_at` string, date-time, nullable — When the experiment started
  - `stopped_at` string, date-time, nullable — When the experiment stopped
  - `created_at` string, date-time, required — When the experiment was created
  - `updated_at` string, date-time, required — When the experiment was last written
  - `last_updated_by` string, required — Who last wrote it
  - `target` DaoExperimentTargetSummary — The channel target an experiment splits, resolved for display. Enough to name the target on the experiment card without a second read: the Console shows the target itself and the channel it belongs to, and links to neither by ID.
    - `id` integer, required — The internal ID of the channel target
    - `target` string, required — The target itself, such as a phone number
    - `target_mode` 'voice' | 'chat' | 'sms' | 'email' | 'whatsapp', required — Available modes (communication methods) for channel targets.
    - `channel_id` integer, required — The channel the target belongs to
    - `channel_name` string, required — The name of that channel

## Other responses

- `400` — Bad Request
- `404` — Not Found
- `409` — Conflict
- `422` — Validation Error

## Changes

> 144 revisions in range; 1 not diffed.

- **2026-09-15** `f353cf6261b7` — 1 info
  - added the non-success response with the status `409`
- **2026-09-10** `3e1a553bd816` — 1 info
  - endpoint added

[Change history](https://skmtc.dev/asksyllable/apis/syllablesdk/changes/api/v1/experiments/:experiment_id/put.md)

---

[API](https://skmtc.dev/asksyllable/apis/syllablesdk.md) · [All operations](https://skmtc.dev/asksyllable/apis/syllablesdk/llms.txt) · [OpenAPI document](https://skmtc.dev/asksyllable/apis/syllablesdk/revisions/38f95bc17acb?raw)