> 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 create OligoConjugate

POST https://{tenant_name}.benchling.com/api/v3/oligo-conjugate:batch-create
Content-Type: application/json

Batch create OligoConjugate synchronously in one transaction. Maximum 25 items per request.

Reference: https://docs.benchling.com/docs/api/benchling-api/oligo-conjugate/batchcreate

## 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 OligoConjugateCreate, required)

## Response

### 201

Created

- `items` (list of OligoConjugate, required)

## Errors

### 400 Oligo Conjugate Batch Create 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 Oligo Conjugate Batch Create 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 Oligo Conjugate Batch Create 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 Oligo Conjugate Batch Create 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 Oligo Conjugate Batch Create 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)

### 500 Oligo Conjugate Batch Create 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

### OligoConjugateCreate

- `componentMapping` (map from string to string, required) — Mapping from schema component names to entity names.
- `connections` (string, required) — Connection definitions for the complex polymer structure, as pipe-delimited entries. Each entry is `sourceLabel,targetLabel` for a shorthand covalent bond between two small molecules, or `sourceLabel,targetLabel,residueIndex:rGroupOrPair-residueIndex:rGroupOrPair` for a HELM-style attachment. Labels refer to component names from componentMapping, suffixed with `(N)` to disambiguate repeated entities (e.g. `molecule(2)`). For example: `oligoName,moleculeName,1:R1-?:?|moleculeName,molecule2Name`.
- `folderId` (string, required)
- `name` (string, required) — Name of the item.
- `schemaId` (string, required) — The ID of the schema to use for the oligo conjugate.
- `aliases` (list of string, optional)
- `authorIds` (list of string, optional)
- `customFields` (map from string to FieldValueInput, optional)
- `entityRegistryId` (string, optional) — Registry ID to assign to the entity. If one is specified, the labeling_strategy must be unspecified.
- `namingStrategy` (enum, optional) — Strategy to use for labeling the item in the registry. 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. If not null, the value must match the registry of the item's schema.
- `schemaFields` (map from string to FieldValueInput, optional)

### OligoConjugate

- `__typename` (string, optional)
- `authors` (string, optional, nullable)
- `creator` (PrincipalRef, optional)
- `schemaFields` (list of SchemaFieldValue, optional, nullable)
- `aliases` (list of string, optional, nullable)
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `backbone` (NucleotideSimplePolymer, optional) — Represents a nucleic acid strand (DNA or RNA) within a complex polymer structure. Contains the sequence residues and connections to other polymers. The entity field links to a corresponding DnaSequence, RnaSequence, DnaOligo, or RnaOligo. Used as the backbone component in OligoConjugate and as forward/reverse strands in OligoDuplex.
- `canonicalHelm` (string, optional)
- `conjugates` (list of IOligoConjugateConjugatesItem, optional)
- `createdAt` (string, optional)
- `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)
- `name` (string, optional) — Name of the item.
- `originalHelm` (string, optional, nullable)
- `outOfSync` (boolean, optional)
- `outOfSyncReason` (string, optional, nullable)
- `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) — Use typedSchema instead, which returns the per-type schema.
- `structure` (OligoConjugateStructure, optional) — Contains the complete structural definition of an oligo conjugate, including its oligonucleotide backbone, conjugated molecules and peptides, and the connections between them. For each simple polymer, restricted read access on the linked entity affects `entity` only; structural fields on that polymer are still populated for the containing conjugate.
- `typedSchema` (OligoConjugateSchemaRef, optional)

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

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

### NucleotideSimplePolymer

Represents a nucleic acid strand (DNA or RNA) within a complex polymer structure. Contains the sequence residues and connections to other polymers. The entity field links to a corresponding DnaSequence, RnaSequence, DnaOligo, or RnaOligo. Used as the backbone component in OligoConjugate and as forward/reverse strands in OligoDuplex.

- `__typename` (string, optional)
- `connections` (list of MolecularConnection, optional) — This polymer's connections to other polymers in the complex polymer.
- `entity` (NucleotideSequenceRef, optional) — The Benchling entity information for this simple polymer.
- `helmReference` (string, optional) — The HELM reference of this polymer (e.g. RNA1). Uniquely identifies this simple polymer in the context of a single complex polymer.
- `nucleotideType` (enum, optional) — Whether this strand is DNA or RNA.
  - Allowed values: `DNA`, `RNA`
- `polymerType` (string, optional) — The HELM polymer type for this strand. This is always `RNA` for nucleotide simple polymers, including DNA sequences. Use `nucleotideType` to distinguish DNA from RNA.
- `residues` (string, optional) — The nucleotide base sequence of this strand.

### IOligoConjugateConjugatesItem

Union of NucleotideSimplePolymer, ChemSimplePolymer

### 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)

### OligoConjugateStructure

Contains the complete structural definition of an oligo conjugate, including its oligonucleotide backbone, conjugated molecules and peptides, and the connections between them. For each simple polymer, restricted read access on the linked entity affects `entity` only; structural fields on that polymer are still populated for the containing conjugate.

- `__typename` (string, optional)
- `connections` (list of MolecularConnection, optional) — A list of all the connections between simple polymers in this oligo conjugate.
- `resolvedAttachments` (list of MolecularConjugate, optional) — A list of attachment information, providing a more detailed chemical structure for a set of connections.
- `simplePolymers` (list of OligoConjugateStructureSimplePolymersItem, optional) — A list of all the simple polymers in this oligo conjugate.

### OligoConjugateSchemaRef

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

### SchemaFieldDefinitionRef

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

### SchemaFieldValueValue

### MolecularConnection

Represents a chemical bond between two polymers within a complex polymer structure. Connections can be covalent bonds (including disulfide bonds) or hydrogen bonds (for base pairing in duplexes). Each connection has source and target ConnectionSide endpoints defining which polymers and residues are bonded. The attachmentStyle indicates whether the connection was drawn graphically or specified via leaving groups.

- `__typename` (string, optional)
- `attachmentStyle` (enum, optional, nullable) — The format in which the user has defined the connection (i.e. drawn vs leaving group style). Only applicable to covalent bond type connections.
  - Allowed values: `LEAVING_GROUP`, `DRAWN`
- `connectionType` (enum, optional) — The kind of chemical bond this connection represents.
  - Allowed values: `COVALENT_BOND`, `HYDROGEN_BOND`
- `covalentBondType` (enum, optional, nullable) — The type of covalent bond represented by the connection (i.e. disulfide bond or not). Only applicable to covalent bond type connections.
  - Allowed values: `DISULFIDE_BOND`
- `source` (ConnectionSide, optional) — 'source' and 'target' are interchangeable - connections are bidirectional.
- `target` (ConnectionSide, optional) — Represents one endpoint of a connection between polymers in a complex polymer structure. Identifies the specific attachment point including the polymer reference, residue position (for sequences), modification type (for nucleotides), and R-group number (for specific attachment sites on monomers). Each MolecularConnection has a source and target ConnectionSide defining the two endpoints of the bond.

### NucleotideSequenceRef

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

### ChemSimplePolymer

Represents a small molecule within a complex polymer structure. Contains SMILES and molfile representations of the chemical structure, along with connections to other polymers. The entity field links to a corresponding `Molecule`. Commonly used as conjugate payloads attached to oligonucleotide backbones, such as lipid nanoparticles, fluorescent labels, or therapeutic molecules.

- `__typename` (string, optional)
- `connections` (list of MolecularConnection, optional) — This polymer's connections to other polymers in the complex polymer.
- `entity` (MoleculeRef, optional) — The Benchling entity information for this simple polymer.
- `helmReference` (string, optional) — The HELM reference of this polymer (e.g. CHEM1). Uniquely identifies this simple polymer in the context of a single complex polymer.
- `molfile` (string, optional) — The molfile representation of this small molecule's chemical structure.
- `polymerType` (string, optional) — The HELM polymer type for this small molecule. This is always `CHEM` for chem simple polymers.
- `smiles` (string, optional) — The chemical structure of this small molecule in SMILES format.

### DocumentLikeRef

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

### MolecularConjugate

Detailed information about a molecular conjugate formed by a group of contiguous connections in a complex polymer. The entire chemical structure of the molecular conjugate, and any components inside it, is represented by a molfile. This allows for the representation of any bond chemistry, beyond the simple leaving group style supported by HELM. For example, suppose we have two involved connections, one between a backbone oligo and a linker molecule, and another between the linker molecule and a payload molecule. Then the molfile would represent the entire complex of: - the monomer on the backbone where the linker attaches - the connection between monomer and linker - the linker molecule - the connection between linker and payload - the payload molecule Currently, this structure will only represent user-drawn attachments. However, in the future, this object may also contain leaving group style connections as well.

- `__typename` (string, optional)
- `connectionsInvolved` (list of MolecularConnection, optional) — The molecular connections that comprise this conjugate. Together these connections define the bonded region represented by the molfile.
- `molfile` (string, optional) — The molfile representation of the molecular conjugate's chemical structure, including all bonded components represented by this conjugate.

### OligoConjugateStructureSimplePolymersItem

Union of NucleotideSimplePolymer, ChemSimplePolymer, PeptideSimplePolymer, ProteinSimplePolymer

### 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)

### ConnectionSide

Represents one endpoint of a connection between polymers in a complex polymer structure. Identifies the specific attachment point including the polymer reference, residue position (for sequences), modification type (for nucleotides), and R-group number (for specific attachment sites on monomers). Each MolecularConnection has a source and target ConnectionSide defining the two endpoints of the bond.

- `__typename` (string, optional)
- `modificationType` (enum, optional, nullable) — Benchling has no concept of monomer index like HELM does, so specifying the modification type is our way of telling the particular monomer for an attachment on a nucleotide polymer. For non-nucleotide polymers, this is always null since we would only have one monomer at a particular index.
  - Allowed values: `SUGAR`, `BASE`, `PHOSPHATE`
- `polymerRef` (string, optional) — The ref of the simple polymer connected at this attachment point.
- `rGroup` (integer, optional, nullable) — The r-group number designates the specific attachment site on the monomer used by this connection. If not null, always >= 1.
- `residueIndex` (integer, optional, nullable) — For sequence types, the index of the residue at this attachment point. residueIndex is always 0 or null for CHEM polymers since we never have more than one "residue".

### MoleculeRef

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

### PeptideSimplePolymer

Represents a peptide or protein chain within a complex polymer structure. Contains the amino acid residue sequence and connections to other polymers. The entity field links to a corresponding `AaSequence`. Used when protein/aa-sequence components are part of larger bioconjugate structures.

- `__typename` (string, optional)
- `connections` (list of MolecularConnection, optional) — This polymer's connections to other polymers in the complex polymer.
- `entity` (AaSequenceRef, optional) — The Benchling entity information for this simple polymer.
- `helmReference` (string, optional) — The HELM reference of this polymer (e.g. PEPTIDE1). Uniquely identifies this simple polymer in the context of a single complex polymer.
- `polymerType` (string, optional) — The HELM polymer type for this peptide or protein chain. This is always `PEPTIDE` for peptide simple polymers.
- `residues` (string, optional) — The amino acid residue sequence of this peptide or protein chain.

### ProteinSimplePolymer

Represents a protein nested by reference within a complex polymer structure, along with connections to other polymers. The entity field links to the corresponding `Protein`, and the nested protein's own structure stays on that protein rather than being copied into the containing structure.

- `__typename` (string, optional)
- `connections` (list of MolecularConnection, optional) — This polymer's connections to other polymers in the complex polymer.
- `entity` (ProteinRef, optional) — The nested protein. This always reflects the protein's current state, which can differ from `nestedComplexPolymerVersion` if the protein has changed since the containing structure was written.
- `helmReference` (string, optional) — The HELM reference of this polymer (e.g. PROTEIN1). Uniquely identifies this simple polymer in the context of a single complex polymer.
- `nestedComplexPolymerVersion` (ProteinVersionRef, optional, nullable) — The version of the nested protein that the containing structure was written against. Null when the viewer cannot read the nested protein.
- `polymerType` (string, optional) — The HELM polymer type for this nested protein. This is always `PROTEIN` for protein simple polymers.

### ObjectRef

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

### ArrayValueValueItem

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

### AaSequenceRef

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

### ProteinRef

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

### ProteinVersionRef

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

## Examples

**Request**

```json
{
  "items": [
    {
      "componentMapping": {
        "key": "value"
      },
      "connections": "connections",
      "folderId": "folderId",
      "name": "name",
      "schemaId": "schemaId"
    }
  ]
}
```

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "authors": "authors",
      "schemaFields": [
        {}
      ],
      "aliases": [
        "aliases"
      ],
      "archiveReason": "archiveReason",
      "archived": true,
      "canonicalHelm": "canonicalHelm",
      "conjugates": [
        {}
      ],
      "createdAt": "createdAt",
      "customFields": [
        {}
      ],
      "entityRegistryId": "entityRegistryId",
      "id": "id",
      "modifiedAt": "modifiedAt",
      "name": "name",
      "originalHelm": "originalHelm",
      "outOfSync": true,
      "outOfSyncReason": "outOfSyncReason"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/oligo-conjugate:batch-create"

payload = { "items": [
        {
            "componentMapping": { "key": "value" },
            "connections": "connections",
            "folderId": "folderId",
            "name": "name",
            "schemaId": "schemaId"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

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

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/oligo-conjugate:batch-create';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"items":[{"componentMapping":{"key":"value"},"connections":"connections","folderId":"folderId","name":"name","schemaId":"schemaId"}]}'
};

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