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

# List OligoDuplex items

GET https://{tenant_name}.benchling.com/api/v3/oligo-duplex/items

List OligoDuplex items.

Reference: https://docs.benchling.com/docs/api/benchling-api/oligo-duplex/list

## Authentication

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

## Request

### Query parameters

- `archiveReason.anyOf` (string, optional) — Restricts items to those with any of the specified archive reasons. Use "NOT_ARCHIVED" to filter for unarchived items. Use "ANY_ARCHIVED" to filter for archived items regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived. Comma-separated list.
- `archived.anyOf` (boolean, optional) — If true, returns archived items. If false, returns unarchived items. If both true and false, returns archived and unarchived items. Comma-separated list.
- `authors.anyOf` (string, optional) — Restricts results to those whose author matches any of the specified user or author IDs. Comma-separated list.
- `createdAt.gt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created after the specified time. e.g. > 2017-04-30.
- `createdAt.gte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or after the specified time. e.g. >= 2017-04-30.
- `createdAt.lt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created before the specified time. e.g. \< 2017-04-30.
- `createdAt.lte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or before the specified time. e.g. \<= 2017-04-30.
- `creator.anyOf` (string, optional) — Restricts results to those created by any of the specified user IDs. Comma-separated list.
- `entityRegistryIds.anyOf` (string, optional) — Restricts results to those that match any of the specified entity registry IDs. Comma-separated list.
- `fieldset.anyOf` (string, optional) — Restricts results to those whose schema implements any of the specified fieldset API IDs (custom schema interfaces). Comma-separated list.
- `id.anyOf` (string, optional) — Restricts results to those matching any of the specified IDs. Comma-separated list.
- `mentionedIn.anyOf` (string, optional) — Restricts results to items mentioned in entries matching any of the specified entry IDs. Comma-separated list.
- `modifiedAt.gt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified after the specified time. e.g. > 2017-04-30.
- `modifiedAt.gte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or after the specified time. e.g. >= 2017-04-30.
- `modifiedAt.lt` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified before the specified time. e.g. \< 2017-04-30.
- `modifiedAt.lte` (string, optional) — Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or before the specified time. e.g. \<= 2017-04-30.
- `name.anyOf` (string, optional) — Restricts results to those that match any of the specified names. Case insensitive. Warning - this filter can be non-performant due to case insensitivity. Ensure only one name filter is used at a time. Comma-separated list.
- `name.anyOf.caseSensitive` (string, optional) — Restricts results to those that match any of the specified names. Case sensitive. Ensure only one name filter is used at a time. Comma-separated list.
- `nextToken` (string, optional) — Token for pagination
- `omit` (string, optional) — Comma-separated list of top-level fields to omit from each returned item. Cannot overlap with returning.
- `pageSize` (integer, optional) — Number of results to return. Defaults to 50, maximum of 100.
- `project.eq` (string, optional) — ID of a project. Restricts results to those in the project.
- `registry.eq` (string, optional) — ID of a registry. Restricts results to those registered in this registry. Specifying "null" returns unregistered items.
- `returning` (string, optional) — Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit.
- `schema.anyOf` (string, optional) — Restricts results to those that match any of the specified schema IDs. Use only one `schema` filter arg at a time. Comma-separated list.
- `schema.eq` (string, optional) — Single schema ID. Restricts results to those that match the specified schema exactly. Use only one `schema` filter arg at a time.
- `systemCategory.anyOf` (string, optional) — Restricts results to those whose schema implements any of the specified system category API IDs (non-exclusive static schema interfaces). Comma-separated list.
- `sort` (enum, optional, default: modifiedAt:desc) — Method by which to order results. Valid sorts are: createdAt (created time, oldest first) and modifiedAt (modified time, oldest first). Use :asc or :desc to specify ascending or descending order. Default is modifiedAt:desc.
  - Allowed values: `createdAt:asc`, `createdAt:desc`, `modifiedAt:asc`, `modifiedAt:desc`

### Headers

- `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3.

## Response

### 200

OK

- `items` (list of OligoDuplex, optional)
- `nextToken` (string, optional)

## Errors

### 400 Oligo Duplex List 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 Duplex List 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 Duplex List 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)

### 429 Oligo Duplex List 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 Duplex List 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

### OligoDuplex

- `__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)
- `canonicalHelm` (string, optional)
- `conjugates` (list of IOligoDuplexConjugatesItem, 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)
- `forwardOffset` (integer, optional, nullable)
- `forwardStrand` (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.
- `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.
- `reverseStrand` (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.
- `schema` (EntitySchemaRef, optional) — Use typedSchema instead, which returns the per-type schema.
- `structure` (OligoDuplexStructure, optional) — Contains the complete structural definition of an oligo duplex, including its forward and reverse strands, any 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 duplex.
- `typedSchema` (OligoDuplexSchemaRef, optional)

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

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

### IOligoDuplexConjugatesItem

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)

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

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

### OligoDuplexStructure

Contains the complete structural definition of an oligo duplex, including its forward and reverse strands, any 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 duplex.

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

### OligoDuplexSchemaRef

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

### SchemaFieldDefinitionRef

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

### SchemaFieldValueValue

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

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

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

### OligoDuplexStructureSimplePolymersItem

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)

### MoleculeRef

- `__typename` (string, optional)
- `id` (string, 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".

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

**Response**

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

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/oligo-duplex/items"

headers = {"Authorization": "Bearer <token>"}

response = requests.get(url, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/oligo-duplex/items';
const options = {method: 'GET', headers: {Authorization: 'Bearer <token>'}};

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