> 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.

# Batch update Molecule

PATCH https://{tenant_name}.benchling.com/api/v3/molecule:batch-update
Content-Type: application/json

Batch update Molecule synchronously in one transaction. Maximum 25 items per request.

Reference: https://docs.benchling.com/docs/api/benchling-api/molecule/batchupdate

## Authentication

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

## Request

### Body (application/json)

This endpoint expects an object.

- `items` (list of UpdateMoleculeInputWithPathParams, required)

## Response

### 200

OK

- `items` (list of Molecule, required)

## Errors

### 400 Molecule Batch Update Request Bad Request Error

Bad Request

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 403 Molecule Batch Update Request Forbidden Error

Forbidden

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 404 Molecule Batch Update Request Not Found Error

Not Found

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 409 Molecule Batch Update Request Conflict Error

Conflict

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 429 Molecule Batch Update Request Too Many Requests Error

Too Many Requests

- `detail` (TooManyRequestsErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)
- `violated-policies` (list of enum, optional) — The budget policies that rejected the request, in canonical order: `user`, `integration`, then `tenant`.
  - Allowed values: `user`, `integration`, `tenant`

### 500 Molecule Batch Update Request Internal Server Error

Internal Server Error

- `detail` (InternalServerErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `errorId` (string, optional)

## Types

### UpdateMoleculeInputWithPathParams

- `id` (string, required) — API identifier of the registry item to update.
- `aliases` (list of string, optional)
- `allowCustomFieldDeletion` (boolean, optional) — When true, custom fields present on the entity but omitted from the update payload will be deleted. When false or omitted, omitting existing custom fields is an error. Defaults to false.
- `archiveReason` (string, optional)
- `archived` (boolean, optional)
- `authorIds` (list of string, optional)
- `chemicalStructure` (ChemicalStructureInput, optional)
- `customFields` (map from string to FieldValueInput, optional)
- `entityRegistryId` (string, optional) — Registry ID to assign to the entity. When registering, specifying this value sets the registry ID of the entity. When already registered, specifying this value updates the entity's registry ID. If set, naming_strategy must be unspecified.
- `folderId` (string, optional)
- `name` (string, optional) — Name of the item.
- `namingStrategy` (enum, optional) — Strategy to use for labeling the item in the registry if registering. If one is specified, the entity_registry_id must be unspecified.
  - Allowed values: `NEW_IDS`, `IDS_FROM_NAMES`, `DELETE_NAMES`, `SET_FROM_NAME_PARTS`, `REPLACE_NAMES_FROM_PARTS`, `KEEP_NAMES`, `REPLACE_ID_AND_NAME_FROM_PARTS`
- `registryId` (string, optional, nullable) — A not null value means the entity should be registered. A null value means it should be unregistered. If not null, the value must match the registry of the item's schema.
- `schemaFields` (map from string to FieldValueInput, optional)
- `schemaId` (string, optional)

### Molecule

- `__typename` (string, optional)
- `authors` (string, optional, nullable)
- `creator` (PrincipalRef, optional, nullable)
- `schemaFields` (list of SchemaFieldValue, optional, nullable)
- `aliases` (list of string, optional, nullable)
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `canonicalSmiles` (string, optional, nullable) — The canonicalized chemical structure in SMILES format. E.g., Nc1nc(=O)n([H:1])cc1C1CC1
- `createdAt` (string, optional, nullable)
- `customFields` (list of CustomField, optional, nullable)
- `entityRegistryId` (string, optional, nullable) — The registry-assigned identifier for this item (e.g. its registry ID shown in the UI), present only once the item has been registered. Null if the item is not registered.
- `folder` (FolderRef, optional, nullable)
- `id` (string, optional)
- `modifiedAt` (string, optional, nullable)
- `name` (string, optional, nullable) — Name of the item.
- `originalSmiles` (string, optional, nullable) — The original chemical structure in SMILES format. Null if the user did not originally provide SMILES. E.g., Nc1nc(=O)n([H:1])cc1C1CC1
- `project` (ProjectRef, optional, nullable)
- `registrationOrigin` (RegistrationOrigin, optional, nullable) — Provenance of this item's registration — where and when it was registered. Null if unregistered.
- `registry` (RegistryRef, optional, nullable) — The Registry this item belongs to, if registered. Null if unregistered.
- `schema` (EntitySchemaRef, optional, nullable) — Use typedSchema instead, which returns the per-type schema.
- `smilesWithCounterparts` (string, optional, nullable) — The full chemical structure in SMILES format, including salt and solvent counterparts as dot-disconnected fragments (each repeated according to its ratio). When a compound has no counterparts, this equals canonicalSmiles.
- `typedSchema` (MoleculeSchemaRef, optional, nullable)

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### ChemicalStructureInput

- `structureFormat` (enum, required)
  - Allowed values: `smiles`, `molfile`
- `value` (string, required) — Chemical structure in SMILES or molfile format. Pass an empty SMILES string to create a Molecule with no defined structure (equivalent to leaving the structure blank in the app's sketcher).

### FieldValueInput

- `value` (any, required)

### PrincipalRef

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

### SchemaFieldValue

Represents a field value on a schematized object, pairing a `fieldDefinition` (describing the field's type and constraints) with its actual `value` (a `BenchlingValue` such as text, number, date, or link to another object). The value may be null if no value has been set. Used within the `schemaFields` collection on objects that implement `HasSchema` to provide access to all custom field values defined by the object's schema.

- `__typename` (string, optional)
- `fieldDefinition` (SchemaFieldDefinitionRef, optional)
- `id` (string, optional)
- `linkedEntityId` (string, optional, nullable)
- `value` (SchemaFieldValueValue, optional, nullable) — Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue, ArrayValue

### CustomField

A name-value pair for storing additional metadata on objects that support custom fields. CustomFields provide a flexible way to attach arbitrary string data to entities, containers, datasets, and other Benchling objects without modifying their schemas. Objects that can have custom fields implement the HasCustomFields interface. Unlike schema-defined fields, custom fields are not validated against a schema and can be freely added or modified.

- `__typename` (string, optional)
- `name` (string, optional, nullable)
- `value` (string, optional, nullable)

### FolderRef

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

### ProjectRef

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

### RegistrationOrigin

Captures the provenance of an entity's registration into the registry. The `originEntry` links to the `DocumentLike` (typically an entry or notebook) from which the entity was registered, providing traceability back to the original experimental context. The `registeredAt` timestamp records when the registration occurred. This information helps scientists understand where registered entities came from and when they were added to the registry.

- `__typename` (string, optional)
- `originEntry` (DocumentLikeRef, optional, nullable)
- `registeredAt` (string, optional, nullable)

### RegistryRef

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

### EntitySchemaRef

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

### MoleculeSchemaRef

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

### SchemaFieldDefinitionRef

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

### SchemaFieldValueValue

### DocumentLikeRef

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

### BooleanValue

A type that represents boolean values.

- `__typename` (string, optional)
- `value` (boolean, optional) — The boolean value.

### DateTimeValue

A type that represents datetime values.

- `__typename` (string, optional)
- `value` (string, optional) — The datetime value with UTC as the timezone.

### DateValue

A type that represents date values.

- `__typename` (string, optional)
- `value` (date, optional) — The date value.

### DecimalValue

A type that represents decimal value as strings.

- `__typename` (string, optional)
- `value` (string, optional, nullable) — The decimal value in a string representation
- `numericValue` (double, optional, nullable, deprecated) — Deprecated. The float representation of the decimal value.

### IntegerValue

A type that represents integer values.

- `__typename` (string, optional)
- `value` (integer, optional) — The integer value.

### JsonValue

A type that represents JSON values.

- `__typename` (string, optional)
- `value` (map from string to any, optional) — The JSON value.

### ObjectLinkValue

A type that represents links to other objects.

- `__typename` (string, optional)
- `value` (ObjectRef, optional) — The object that this value links to, or an Inaccessible object if not found with the current permission set.

### ObjectLinkListValue

A type that represents a list of links to other objects.

- `__typename` (string, optional)
- `value` (list of ObjectRef, optional) — The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set.

### TextAndUrlValue

A type that represents text (string) values with an associated URL.

- `__typename` (string, optional)
- `url` (string, optional) — The URL associated with the value. Please use `TextValue` if you don't want a URL.
- `value` (string, optional) — The text value. It may or may not be an empty string.

### TextValue

A type that represents text (string) values.

- `__typename` (string, optional)
- `value` (string, optional) — The text value. It may or may not be an empty string.

### ArrayValue

A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns).

- `__typename` (string, optional)
- `value` (list of ArrayValueValueItem, optional)

### ObjectRef

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

### ArrayValueValueItem

Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue

## Examples

**Request**

```json
{
  "items": [
    {
      "id": "id"
    }
  ]
}
```

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "authors": "authors",
      "schemaFields": [
        {}
      ],
      "aliases": [
        "aliases"
      ],
      "archiveReason": "archiveReason",
      "archived": true,
      "canonicalSmiles": "canonicalSmiles",
      "createdAt": "createdAt",
      "customFields": [
        {}
      ],
      "entityRegistryId": "entityRegistryId",
      "id": "id",
      "modifiedAt": "modifiedAt",
      "name": "name",
      "originalSmiles": "originalSmiles",
      "smilesWithCounterparts": "smilesWithCounterparts"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/molecule:batch-update"

payload = { "items": [{ "id": "id" }] }
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/v3/molecule:batch-update';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"items":[{"id":"id"}]}'
};

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