> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# Update a mixture

PATCH https://{tenant_name}.benchling.com/api/v2/mixtures/{mixture_id}
Content-Type: application/json

Update a mixture.
To change the parent mixture, set the parent mixture field and specify the desired final state for your ingredients.
Benchling will recognize that any ingredients you specify that match ingredients on the parent mixture (based on component entity) are inherited. This can be seen on the returned `ingredients[i].hasParent` attribute.


Reference: https://docs.benchling.com/docs/api/v2/benchling-api/mixtures/update-mixture

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `mixture_id` (string, required)

### Body (application/json)

This endpoint expects a MixtureUpdate.

- `aliases` (list of string, optional) — Aliases to add to the mixture
- `amount` (string, optional) — The positive numerical amount value of this mixture in string format (to preserve full precision). Pair with `units`. Supports scientific notation (1.23e4).
- `authorIds` (list of string, optional) — IDs of users to set as the mixture's authors.
- `customFields` (map from string to CustomField, optional) — Custom fields to add to the mixture. Every field should have its name as a key, mapping to an object with information about the value of the field.
- `entityRegistryId` (string, optional)
- `fields` (map from string to Field, optional) — Schema fields to set on the mixture. Must correspond with the schema's field definitions. Every field should have its name as a key, mapping to an object with information about the value of the field. If you are setting the parent mixture field here, you must also specify `ingredients`
- `folderId` (string, optional) — ID of the folder that the entity is moved into
- `ingredients` (list of IngredientWriteParams, optional) — Desired final state for the ingredients on this mixture. Each ingredient you specify will be matched with the existing ingredients on the mixture based on the component entity, and Benchling will create, update, or delete this mixture's ingredients so that the final state of this mixture's ingredients matches your request. Benchling will recognize that any ingredients you specify that match ingredients on the parent mixture (based on component entity) are inherited. This can be seen on the returned `ingredients[i].hasParent` attribute.
- `name` (string, optional)
- `schemaId` (string, optional)
- `units` (enum, optional)
  - Allowed values: `nL`, `uL`, `mL`, `L`, `g`, `kg`, `mg`, `ug`, `Units`

## Response

### 200

OK

- `aliases` (list of string, optional)
- `allowMeasuredIngredients` (boolean, optional) — Derived from the mixture's schema.
- `amount` (string, optional) — The positive numerical amount value of this mixture in string format (to preserve full precision). Pair with `units`. Supports scientific notation (1.23e4).
- `apiURL` (string, optional) — The canonical url of the Mixture in the API.
- `archiveRecord` (ArchiveRecord, optional, nullable)
- `authors` (list of UserSummary, optional)
- `createdAt` (datetime, optional)
- `creator` (MixtureCreator, optional)
- `customFields` (map from string to CustomField, optional)
- `entityRegistryId` (string, optional, nullable)
- `fields` (map from string to Field, optional) — Mixtures can have up to one parent mixture field.
- `folderId` (string, optional, nullable)
- `id` (string, optional)
- `ingredients` (list of Ingredient, optional) — List of ingredients on this mixture.
- `modifiedAt` (datetime, optional)
- `name` (string, optional)
- `registrationOrigin` (RegistrationOrigin, optional, nullable)
- `registryId` (string, optional, nullable)
- `schema` (SchemaSummary, optional)
- `units` (enum, optional)
  - Allowed values: `nL`, `uL`, `mL`, `L`, `g`, `kg`, `mg`, `ug`, `Units`
- `webURL` (string, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

## Types

### CustomField

- `value` (string, optional)

### Field

- `value` (FieldValue, required, nullable) — For single link fields, use the id of the item you want to link (eg. "seq_jdf8BV24"). For multi-link fields, use an array of ids of the items you want to link (eg. ["seq_jdf8BV24"])
- `displayValue` (string, optional, nullable)
- `isMulti` (boolean, optional)
- `textValue` (string, optional, nullable)
- `type` (enum, optional)
  - Allowed values: `dna_sequence_link`, `aa_sequence_link`, `custom_entity_link`, `entity_link`, `mixture_link`, `molecule_link`, `dropdown`, `part_link`, `translation_link`, `aa_part_link`, `base_molecule_link`, `blob_link`, `text`, `long_text`, `batch_link`, `storage_link`, `entry_link`, `assay_request_link`, `assay_result_link`, `assay_run_link`, `boolean`, `float`, `integer`, `datetime`, `date`, `json`

### IngredientWriteParams

- `amount` (string, required, nullable) — The amount value of this ingredient in its mixture, in string format (to preserve full precision). Pair with `units`. Supports scientific notation (1.23e4). One ingredient on this mixture can have an amount value of `"QS"`.
- `catalogIdentifier` (string, required, nullable)
- `componentEntityId` (string, required) — The entity that uniquely identifies this component.
- `componentLotContainerId` (string, required, nullable) — The container representing the component lot for this ingredient. This is only writable if the mixture schema supports component lots in "inventory" format.
- `componentLotEntityId` (string, required, nullable) — The entity representing the component lot for this ingredient. This is only writable if the mixture schema supports component lots in "inventory" format.
- `componentLotText` (string, required, nullable) — Text representing the component lot for this ingredient. This is only writable if the mixture schema supports component lots in "text" format.
- `notes` (string, required, nullable)
- `units` (enum, required)
  - Allowed values: `nL`, `uL`, `mL`, `L`, `mg`, `g`, `kg`, `ug`, `Units`, `Cells`, `mol`, `mmol`, `umol`

### ArchiveRecord

- `reason` (string, optional)

### UserSummary

- `handle` (string, optional)
- `id` (string, optional)
- `name` (string, optional)

### MixtureCreator

- `handle` (string, optional)
- `id` (string, optional)
- `name` (string, optional)

### Ingredient

- `amount` (string, optional, nullable) — The amount value of this ingredient in its mixture, in string format (to preserve full precision). Pair with `units`. Supports scientific notation (1.23e4). One ingredient on this mixture can have an amount value of `"QS"`.
- `catalogIdentifier` (string, optional, nullable)
- `componentEntity` (IngredientComponentEntity, optional) — The entity that uniquely identifies this component.
- `componentLotContainer` (ContainerLabels, optional, nullable) — The container representing the component lot for this ingredient. This is only present if the mixture schema supports component lots in "inventory" format.
- `componentLotEntity` (EntityLabels, optional, nullable) — The entity representing the component lot for this ingredient. This is only present if the mixture schema supports component lots in "inventory" format.
- `componentLotText` (string, optional, nullable) — Text representing the component lot for this ingredient. This is only present if the mixture schema supports component lots in "text" format.
- `hasParent` (boolean, optional)
- `notes` (string, optional, nullable)
- `targetAmount` (string, optional, nullable) — The target amount for this ingredient such that this ingredient's proportion in its mixture would preserve the equivalent ingredient's proportion in the parent mixture. Pair with `units`.
- `units` (enum, optional)
  - Allowed values: `nL`, `uL`, `mL`, `L`, `mg`, `g`, `kg`, `ug`, `Units`, `Cells`, `mol`, `mmol`, `umol`

### RegistrationOrigin

- `originEntryId` (string, optional, nullable)
- `registeredAt` (datetime, optional)

### SchemaSummary

- `id` (string, optional)
- `name` (string, optional)

### BadRequestErrorError

- `message` (string, optional)
- `type` (enum, optional)
  - Allowed values: `invalid_request_error`
- `userMessage` (string, optional)

### FieldValue

For single link fields, use the id of the item you want to link (eg. "seq_jdf8BV24"). For multi-link fields, use an array of ids of the items you want to link (eg. ["seq_jdf8BV24"])

### IngredientComponentEntity

The entity that uniquely identifies this component.

- `entityRegistryId` (string, optional, nullable)
- `id` (string, optional)
- `name` (string, optional)

### ContainerLabels

- `barcode` (string, optional)
- `id` (string, optional)
- `name` (string, optional)

### EntityLabels

- `entityRegistryId` (string, optional, nullable)
- `id` (string, optional)
- `name` (string, optional)

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "aliases": [
    "FRM000"
  ],
  "allowMeasuredIngredients": true,
  "amount": "123",
  "apiURL": "https://benchling.com/api/v2/mixtures/mxt_xCUXNVyG",
  "archiveRecord": {
    "reason": "Made in error"
  },
  "authors": [
    {
      "handle": "string",
      "id": "string",
      "name": "string"
    }
  ],
  "createdAt": "2017-04-18T05:54:56.247545+00:00",
  "creator": {
    "handle": "string",
    "id": "string",
    "name": "string"
  },
  "customFields": {
    "Legacy ID": {
      "value": "STR100"
    }
  },
  "entityRegistryId": "FRM000",
  "fields": {},
  "folderId": "lib_R8KcsjhW",
  "id": "mxt_xCUXNVyG",
  "ingredients": [
    {
      "amount": "12",
      "catalogIdentifier": "DION_004",
      "componentEntity": {
        "entityRegistryId": "REAG000",
        "id": "bfi_12345",
        "name": "Deionized Water"
      },
      "componentLotContainer": {
        "barcode": "VIAL001",
        "id": "cnt_12345",
        "name": "My Container"
      },
      "componentLotEntity": {
        "entityRegistryId": "REAG000",
        "id": "bfi_12345",
        "name": "Deionized Water"
      },
      "componentLotText": "DION_004-source_001",
      "hasParent": true,
      "notes": "string",
      "targetAmount": "123",
      "units": "mL"
    }
  ],
  "modifiedAt": "2017-04-18T05:55:48.685345+00:00",
  "name": "FRM000",
  "registrationOrigin": {
    "originEntryId": "string",
    "registeredAt": "2024-01-15T09:30:00Z"
  },
  "registryId": "src_NetYd96a",
  "schema": {
    "id": "ts_EM122lfJ",
    "name": "Prep"
  },
  "units": "L",
  "webURL": "https://benchling.com/benchling/f/R8KcsjhW-academic-registry/mxt-xCUXNVyG-sbn000/edit"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2/mixtures/mixture_id"

payload = {}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v2/mixtures/mixture_id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```