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

# Update experiment

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

## Request

- Base URL: `https://devs.adaptyvbio.com`
- URL: `https://devs.adaptyvbio.com/api/v1/experiments/{experiment_id}`
- Auth: HTTP bearer

Modify an existing experiment's configuration or status.

Updates experiment metadata or inputs. Most fields can only be changed while
the experiment is in Draft or InReview status; naming one on a later status
returns 409 Conflict. `webhook_url` is the exception and stays editable for
the life of the experiment, so a customer can repoint delivery after
submitting.

## Path parameters

- `experiment_id` string, uuid, required

## Request body

- ModifyExpRequest: Request payload for modifying an existing experiment. All fields are optional - only provided fields will be updated. Note: Some modifications may be restricted based on experiment status. Modifications are only allowed if the experiment request is not yet fulfilled. Status transitions are handled separately via the `/experiments/{id}/confirm` endpoint, which performs the appropriate transition based on current state.
  - `antigen_concentrations` number[], nullable: Update antigen concentrations (only if not fulfilled)
  - `description` string, nullable: Update experiment description
  - `n_replicates` integer, nullable: Update replicate count (only if not fulfilled)
  - `name` string, nullable: Update experiment name
  - `parameters` object, nullable: Update experiment parameters (restrictions may apply, only if not fulfilled)
  - `sequences` SequenceEntry[], nullable: Replace sequence list (only if not fulfilled)
    - `aa_string` string, required: A validated amino acid sequence string. Contains only the 20 natural amino acids (single-letter codes: A, C, D, E, F, G, H, I, K, L, M, N, P, Q, R, S, T, V, W, Y) and colons for multichain notation. Input is case-insensitive; stored uppercase. Multichain sequences use colon separators (e.g., `MVLS:EVQL` for a two-chain construct). Invalid characters or empty strings are rejected.
    - `control` boolean: Whether the sequence should be treated as a control well
    - `metadata` unknown
    - `name` string, nullable: Optional name for the sequence (e.g., "mAb1", "scFv-001")
  - `target_id` string, nullable: Change the experiment's catalog target (only while the experiment is editable). - omitted: keep the current target - `null`: clear the target - a catalog product UUID (as returned by `GET /targets`): set the target to that product
  - `webhook_url` string, nullable: Update the webhook URL for push notifications. The URL receives an `experiment_update` event for every customer-facing update on the experiment — the same updates that trigger an email notification. Unlike every other field here, this one can be changed at any status, so delivery can be repointed after the experiment has been submitted.

## Response `200`

Experiment modified successfully or no action taken (e.g., already fulfilled)

- ModifyExpResponse: Response confirming experiment modification.
  - `id` string, required: Experiment identifier that was modified
  - `message` string, nullable: Optional message, e.g., if modification is not allowed
  - `updated` boolean, required: Indicates if any changes were applied

## Other responses

- `400`: Invalid modification request, including a replacement sequence list containing duplicates — two sequences sharing normalized residues and tag location (Fabs exempt); also a malformed body, or `Content-Type: application/json` declared with no body sent
- `401`: Invalid or missing authentication token
- `404`: Experiment request not found
- `409`: Modification not allowed (e.g., request already fulfilled)
- `415`: No body was sent, or a body was sent under a content type other than `application/json`. A JSON body is required; every field is optional, so send `{}` if you have nothing to change
- `422`: Well-formed JSON that does not fit `ModifyExpRequest`

---

[API](https://skmtc.dev/adaptyvbio/apis/adaptyv-foundry-api.md) - [All operations](https://skmtc.dev/adaptyvbio/apis/adaptyv-foundry-api/llms.txt) - [OpenAPI document](https://skmtc.dev/adaptyvbio/apis/adaptyv-foundry-api/revisions/5a2228f4bd59?raw)