Every API here is available over the APIs.io API and to AI agents over MCP.
openapi: 3.2.0
info:
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: Benchling Document Part API
version: 2.0.0
description: 'Represents an ordered piece of content within an entry, template, subtemplate, or document.
Each document part wraps one content block and records its container, version, and audit metadata.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'Represents an ordered piece of content within an entry, template, subtemplate, or document.
Each document part wraps one content block and records its container, version, and audit metadata.'
name: DocumentPart
x-bnch-organization: Benchling
paths:
/document-part/items:
get:
description: List DocumentPart items.
operationId: DocumentPart.List
parameters:
- $ref: '#/components/parameters/id.anyOf'
- $ref: '#/components/parameters/modifiedAt.gt'
- $ref: '#/components/parameters/modifiedAt.gte'
- $ref: '#/components/parameters/modifiedAt.lt'
- $ref: '#/components/parameters/modifiedAt.lte'
- $ref: '#/components/parameters/nextToken'
- $ref: '#/components/parameters/omit'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/returning'
- description: 'Method by which to order results. Valid sorts are: modifiedAt (modified time, oldest first). Use :asc or :desc to specify ascending or descending order. Default is modifiedAt:desc.'
in: query
name: sort
schema:
default: modifiedAt:desc
enum:
- modifiedAt:asc
- modifiedAt:desc
type: string
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentPartPaginatedList'
description: OK
headers: {}
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: List DocumentPart items
tags:
- DocumentPart
x-bnch-rate-limit-tier: 4
/document-part/{document_part_id}:
get:
description: Get a single DocumentPart by ID.
operationId: DocumentPart.Get
parameters:
- description: ID of the DocumentPart.
in: path
name: document_part_id
required: true
schema:
type: string
- $ref: '#/components/parameters/returning'
- $ref: '#/components/parameters/omit'
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DocumentPart'
description: OK
headers: {}
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Get DocumentPart by ID
tags:
- DocumentPart
x-bnch-rate-limit-tier: 5
components:
schemas:
AaAnnotation:
description: 'Represents an annotated region on an amino acid sequence (AaSequence). Annotations mark
functional domains, binding sites, post-translational modifications, engineered mutations,
or other biologically significant features. Each annotation defines a start and end
position (0-based, exclusive end), a name, optional type classification, display color,
and descriptive notes. Annotations appear as visual overlays on the sequence viewer.'
properties:
__typename:
type: string
aaSequence:
$ref: '#/components/schemas/AaSequenceRef'
description: AA sequence the annotation belongs to.
color:
description: Hex color when displaying the annotation.
type: string
end:
description: 0-based exclusive end index.
type: integer
id:
description: ID of the annotation.
type: string
name:
description: Name of the annotation.
type: string
notes:
description: Text notes on the annotation.
type: string
start:
description: 0-based inclusive start index.
type: integer
type:
description: Feature type of the annotation.
type:
- 'null'
- string
type: object
Transcription:
description: 'Represents a transcribed region on a DNA sequence that produces an RNA product. Transcriptions
link a region of a DnaSequence to the corresponding RnaSequence entity, enabling traceability
between DNA templates and their RNA transcripts. The position range (start/end) defines
where transcription begins and ends on the DNA template, while strand indicates the
transcribed strand direction. This feature is derived from schema field relationships
rather than being directly editable as an annotation.'
properties:
__typename:
type: string
end:
description: '0-based exclusive end index. For ranges ending at the end of a circular sequence, this value is
always the length of the sequence, never 0.'
type: integer
rnaSequence:
$ref: '#/components/schemas/RnaSequenceRef'
description: RNA sequence this transcription refers to.
start:
description: 0-based inclusive start index.
type: integer
strand:
description: Strand for this transcription; 1 for forward strand, -1 for reverse strand.
type: integer
type: object
DocumentPart:
description: 'Represents an ordered piece of content within an entry, template, subtemplate, or document.
Each document part wraps one content block and records its container, version, and audit metadata.'
properties:
__typename:
type: string
content:
description: Union of SectionDocumentContent, TextDocumentContent, ListItemDocumentContent, HeaderDocumentContent, CodeBlockDocumentContent, UnstructuredTableDocumentContentSummary, AttachmentDocumentContent, BenchlingItemDocumentContent, RunDocumentContent, TextBoxDocumentContent
oneOf:
- anyOf:
- $ref: '#/components/schemas/SectionDocumentContent'
- $ref: '#/components/schemas/TextDocumentContent'
- $ref: '#/components/schemas/ListItemDocumentContent'
- $ref: '#/components/schemas/HeaderDocumentContent'
- $ref: '#/components/schemas/CodeBlockDocumentContent'
- $ref: '#/components/schemas/UnstructuredTableDocumentContentSummary'
- $ref: '#/components/schemas/AttachmentDocumentContent'
- $ref: '#/components/schemas/BenchlingItemDocumentContent'
- $ref: '#/components/schemas/RunDocumentContent'
- $ref: '#/components/schemas/TextBoxDocumentContent'
discriminator:
propertyName: __typename
- type: 'null'
createdAt:
description: 'Timestamp inherited from the document content backing this part. For entry and
document content, this can reflect when the containing document was created,
not when the DocumentPart identifier was created.'
format: datetime
type:
- 'null'
- string
id:
type: string
modifiedAt:
format: datetime
type: string
modifier:
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
versionId:
type: string
type: object
ProteinFormatChainPosition:
description: 'Defines each instance of a polypeptide chain within a `ProteinFormat`, specifying the chain type and
its constituent domains. Each chain position has a unique ref identifier and lists the domain positions
(see `ProteinFormatDomainPosition`) that compose it in order from N-terminus to C-terminus.
For example, a heavy chain position might reference domain positions [VH, CH1, Hinge, CH2, CH3].'
properties:
__typename:
type: string
domainPositions:
description: A list of all the domain positions that make up the chain position, in order
items:
$ref: '#/components/schemas/ProteinFormatDomainPosition'
type: array
ref:
description: 'A unique identifier for a physical component (chain or domain) in a protein format.
This is used to form a HELM reference that is used in the protein''s complex polymer structure.'
type: integer
type:
description: Type of the chain.
enum:
- HEAVY
- LIGHT
- NONE
- ALPHA
- BETA
- JOINING
type: string
type: object
ProteinFormatRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
DocumentEmbeddable:
anyOf:
- $ref: '#/components/schemas/AaSequence'
- $ref: '#/components/schemas/CustomEntity'
- $ref: '#/components/schemas/DnaSequence'
- $ref: '#/components/schemas/Entry'
- $ref: '#/components/schemas/OligoConjugate'
- $ref: '#/components/schemas/OligoDuplex'
- $ref: '#/components/schemas/Protein'
- $ref: '#/components/schemas/UnresolvableEmbeddedItem'
discriminator:
propertyName: __typename
type: object
ProjectRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
Primer:
description: 'Represents a primer binding site on a nucleotide sequence, indicating where an oligonucleotide primer anneals
for PCR amplification or sequencing. The Primer links to an Oligo entity containing the actual primer sequence
and name. Position fields define the binding region on the template (start/end), while bindPosition specifies
the 3'' end of the binding region (critical for extension). The overhangLength indicates how many 5'' bases
extend beyond the binding region (used for adding restriction sites or tags). Strand indicates whether the
primer binds to the forward (1) or reverse (-1) strand.'
properties:
__typename:
type: string
bindPosition:
description: 0-based index of the base at the 3' end of the binding region.
type: integer
end:
description: '0-based exclusive end of the binding region. For ranges ending at the end of a circular sequence,
this value is always the length of the sequence, never 0.'
type: integer
oligo:
$ref: '#/components/schemas/OligoRef'
description: Linked primer entity, which holds the name, bases, and color for this primer bind site.
overhangLength:
description: Number of 5' primer bases that are not part of the binding region.
type: integer
start:
description: 0-based inclusive start of the binding region.
type: integer
strand:
description: Strand for this primer; 1 for forward strand, -1 for reverse strand.
type: integer
type: object
ReviewRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
CustomField:
description: '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.'
properties:
__typename:
type: string
name:
type:
- 'null'
- string
value:
type:
- 'null'
- string
type: object
EntrySchemaRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
RunSchemaRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
SchemaFieldValue:
description: '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.'
properties:
__typename:
type: string
fieldDefinition:
$ref: '#/components/schemas/SchemaFieldDefinitionRef'
id:
type: string
linkedEntityId:
type:
- 'null'
- string
value:
description: Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue, ArrayValue
oneOf:
- anyOf:
- $ref: '#/components/schemas/BooleanValue'
- $ref: '#/components/schemas/DateTimeValue'
- $ref: '#/components/schemas/DateValue'
- $ref: '#/components/schemas/DecimalValue'
- $ref: '#/components/schemas/IntegerValue'
- $ref: '#/components/schemas/JsonValue'
- $ref: '#/components/schemas/ObjectLinkValue'
- $ref: '#/components/schemas/ObjectLinkListValue'
- $ref: '#/components/schemas/TextAndUrlValue'
- $ref: '#/components/schemas/TextValue'
- $ref: '#/components/schemas/ArrayValue'
discriminator:
propertyName: __typename
- type: 'null'
type: object
DnaSequence:
allOf:
- $ref: '#/components/schemas/IDnaSequence'
- description: 'Represents a DNA sequence in Benchling''s molecular biology platform. A `DnaSequence` stores the nucleotide
bases of the forward strand along with rich annotations for biological features such as genes, promoters, and
regulatory elements. Sequences can be linear or circular (controlled by `isCircular`) and support translation
annotations for protein-coding regions (see `Translation`), primer binding sites (see `Primer`), and part
features linking to other sequences (see `DnaPart`). DNA sequences can be registered in the Registry with a
unique `entityRegistryId`, organized in folders, and linked to other entities via schema fields. Also known as
"Sequence" in the Benchling interface, with IDs prefixed by ''seq''.'
properties:
__typename:
type: string
authors:
oneOf:
- format: uri
type: string
- type: 'null'
creator:
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
schemaFields:
oneOf:
- items:
$ref: '#/components/schemas/SchemaFieldValue'
type: array
- type: 'null'
type: object
LinkSpan:
description: LinkSpan is used when we want to apply a URL to a particular span of the text.
properties:
__typename:
type: string
end:
description: The index where the link ends (exclusive).
type: integer
start:
description: The index where the link starts (inclusive).
type: integer
url:
type: string
type: object
AaSequenceRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
OligoConjugate:
allOf:
- $ref: '#/components/schemas/IOligoConjugate'
- description: 'An oligo conjugate is a therapeutic modality consisting of a single-stranded
oligonucleotide backbone with one or more attached conjugate molecules. Common
examples include antisense oligonucleotides (ASOs) with GalNAc ligands for liver
targeting, or siRNA strands with lipid or cholesterol conjugates. The backbone
references the underlying oligo entity, while conjugates lists the attached molecules.
Structure is defined using HELM notation and can be edited via the visual structure
editor. Supports versioning (see OligoConjugateVersion) to track changes over time.'
properties:
__typename:
type: string
authors:
oneOf:
- format: uri
type: string
- type: 'null'
creator:
$ref: '#/components/schemas/PrincipalRef'
schemaFields:
oneOf:
- items:
$ref: '#/components/schemas/SchemaFieldValue'
type: array
- type: 'null'
type: object
DateTimeValue:
description: A type that represents datetime values.
properties:
__typename:
type: string
value:
description: The datetime value with UTC as the timezone.
format: datetime
type: string
type: object
RegistrationOrigin:
description: '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.'
properties:
__typename:
type: string
originEntry:
oneOf:
- $ref: '#/components/schemas/DocumentLikeRef'
- type: 'null'
registeredAt:
format: datetime
type:
- 'null'
- string
type: object
Translation:
description: 'Represents a protein-coding region (CDS) on a nucleotide sequence, showing the translated
amino acid sequence. Translations can span a single contiguous region or multiple regions
for spliced genes (see RegionsListItem). The aminoAcids field contains the computed protein
sequence based on the geneticCode (see CodonTranslationTable). The translateFirstCodonToMethionine
option forces the start codon to encode methionine regardless of the actual codon. Translations
display as colored overlays on the sequence viewer, with the three-letter amino acid codes
shown above the nucleotide bases.'
properties:
__typename:
type: string
aminoAcids:
description: 'Calculated amino acid translation of the specified regions, combining codons across regions if
necessary.'
type: string
color:
description: Hex color when displaying the translation.
type: string
customFields:
description: Custom fields on the translation.
items:
$ref: '#/components/schemas/CustomField'
type: array
end:
deprecated: true
description: '0-based exclusive end index. For ranges ending at the end of a circular sequence, this value is
always the length of the sequence, never 0. Use regions instead for location information.'
type:
- 'null'
- integer
geneticCode:
description: Genetic code for the translation.
enum:
- STANDARD
- VERTEBRATE_MITOCHONDRIAL
- YEAST_MITOCHONDRIAL
- MOLD_PROTOZOAN_COELENTERATE_MITOCHONDRIAL_MYCOPLASMA_SPIROPLASMA
- INVERTEBRATE_MITOCHONDRIAL
- CILIATE_DASYCLADACEAN_HEXAMITA_NUCLEAR
- ECHINODERM_FLATWORM_MITOCHONDRIAL
- EUPLOTID_NUCLEAR
- BACTERIAL_ARCHAEAL_PLANT_PLASTID
- ALTERNATIVE_YEAST_NUCLEAR
- ASCIDIAN_MITOCHONDRIAL
- ALTERNATIVE_FLATWORM_MITOCHONDRIAL
- CHLOROPHYCEAN_MITOCHONDRIAL
- TREMATODE_MITOCHONDRIAL
- SCENEDESMUS_OBLIQUUS_MITOCHONDRIAL
- THRAUSTOCHYTRIUM_MITOCHONDRIAL
- RHABDOPLEURIDAE_MITOCHONDRIAL
- CANDIDATE_DIVISION_SR1_GRACILIBACTERIA
- PACHYSOLEN_TANNOPHILUS_NUCLEAR
- KARYORELICT_NUCLEAR
- CONDYLOSTOMA_NUCLEAR
- MESODINIUM_NUCLEAR
- PERITRICH_NUCLEAR
- BLASTOCRITHIDIA_NUCLEAR
- CEPHALODISCIDAE_MITOCHONDRIAL_UAA_TYR
type: string
name:
description: Name of the translation.
type: string
notes:
description: Text notes on the translation.
type: string
regions:
description: Array of regions of the translation. For single-region translations, this is an array with one element.
items:
$ref: '#/components/schemas/RegionsListItem'
type: array
start:
deprecated: true
description: '0-based inclusive start index.
Use regions instead for location information.'
type:
- 'null'
- integer
strand:
description: Strand for this annotation; 1 for forward strand, -1 for reverse strand.
type: integer
translateFirstCodonToMethionine:
description: Whether or not the first codon has been forced to be translated as methionine.
type: boolean
type: object
FolderRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
OligoRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
CustomEntity:
allOf:
- $ref: '#/components/schemas/ICustomEntity'
- description: 'A flexible, user-defined entity type in Benchling''s Registry. Unlike specialized entity
types such as DnaSequence or Molecule, CustomEntities allow organizations to model any
kind of scientific or business object using configurable EntitySchemas (see `schema`).
CustomEntities support customFields for storing structured data, can be organized into
Folders and Projects, and integrate with Benchling''s collaboration, search, and audit
systems. They are commonly used to represent cell lines, reagents, instruments, or any
domain-specific items that don''t fit predefined entity categories.'
properties:
__typename:
type: string
authors:
oneOf:
- format: uri
type: string
- type: 'null'
creator:
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
schemaFields:
oneOf:
- items:
$ref: '#/components/schemas/SchemaFieldValue'
type: array
- type: 'null'
type: object
Mention:
description: 'Represents an inline mention of another Benchling item within text content.
Mentions allow users to reference entities (sequences, samples, entries, etc.) directly
in their notebook text. The mention appears as a clickable chip displaying the item''s name.'
properties:
__typename:
type: string
itemId:
description: The API identifier of the referenced Benchling item (e.g., seq_XXXXX, etr_XXXXX).
type: string
position:
description: The position in the raw text where this mention is inserted. This is an index into the parent's `text` field.
type: integer
type: object
JsonValue:
description: A type that represents JSON values.
properties:
__typename:
type: string
value:
description: The JSON value.
type: object
type: object
TextAndUrlValue:
description: A type that represents text (string) values with an associated URL.
properties:
__typename:
type: string
url:
description: The URL associated with the value. Please use `TextValue` if you don't want a URL.
type: string
value:
description: The text value. It may or may not be an empty string.
type: string
type: object
ProteinFormatDomainPosition:
description: 'Defines a domain position within a1 `ProteinFormat`, specifying the domain type and identity of each
physical domain in the protein format. Each domain position has a unique ref identifier used
to construct HELM notation for complex polymer structures. Domain positions are grouped into ProteinFormatDomains,
and each group can be uniquely identified by its label, and will be a single amino acid sequence entity in proteins
of this format.'
properties:
__typename:
type: string
optional:
description: Whether this domain is optional in the format. If true, entities of this format may not have this domain.
type: boolean
ref:
description: 'A unique identifier for a physical component (chain or domain) in a protein format.
This is used to form a HELM reference that is used in the protein''s complex polymer structure.'
type: integer
type:
description: Type of the domain
enum:
- VL
- CL
- VH
- VHH
- CH1
- CH2
- CH3
- CH4
- J
- H
- L
- VA
- CA
- VB
- CB
- VG
- CG
- VD
- CD
- F
- ELEMENT
type: string
type: object
RegionsListItem:
description: 'Represents a contiguous position range within a Translation or other multi-region feature.
For spliced genes or complex reading frames, a Translation may span multiple non-contiguous
regions (exons) that are joined during translation. Each RegionsListItem defines one such
segment using 0-based coordinates (start inclusive, end exclusive). For circular sequences,
regions can wrap around, but the end value is always the sequence length rather than 0.'
properties:
__typename:
type: string
end:
description: '0-based exclusive end index. For ranges ending at the end of a circular sequence, this value is
always the length of the sequence, never 0.'
type: integer
start:
description: 0-based inclusive start index.
type: integer
type: object
ChemSimplePolymer:
description: '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.'
properties:
__typename:
type: string
connections:
items:
$ref: '#/components/schemas/ComplexPolymerConnection'
type: array
entity:
$ref: '#/components/schemas/MoleculeRef'
helmReference:
type: string
molfile:
type: string
polymerType:
type: string
smiles:
type: string
type: object
ProteinChain:
description: 'Represents a polypeptide chain within an `Protein`, containing the domain composition. Each chain has a
computed label derived from the format.'
properties:
__typename:
type: string
chainPositions:
description: 'Each chain position of this chain in the protein. If a chain has multiplicity > 1, each chain position
will be listed here.'
items:
$ref: '#/components/schemas/ProteinFormatChainPosition'
type: array
domains:
description: Each domain on the chain, ordered according to the format.
items:
$ref: '#/components/schemas/ProteinDomain'
type: array
entity:
$ref: '#/components/schemas/AaSequenceRef'
description: The amino acid sequence entity associated with the chain.
label:
description: Unique label for the chain, computed from the format.
type: string
type:
description: The type of the chain.
enum:
- HEAVY
- LIGHT
- NONE
- ALPHA
- BETA
- JOINING
type: string
type: object
ComplexPolymerStructure:
description: 'Contains the complete structural definition of a complex polymer, including all
component polymers and their interconnections. This is the core data structure that
defines how oligonucleotides, molecules, and peptides are assembled into bioconjugates.
The simplePolymers list contains all components, connections defines the bonds between
them, and resolvedAttachments provides detailed chemistry for drawn attachments.'
properties:
__typename:
type: string
connections:
description: A list of all the connections between simple polymers in this complex polymer.
items:
$ref: '#/components/schemas/ComplexPolymerConnection'
type: array
resolvedAttachments:
description: A list of attachment information, providing a more detailed chemical structure for a set of connections.
items:
$ref: '#/components/schemas/ComplexPolymerResolvedAttachment'
type: array
simplePolymers:
description: A list of all the simple polymers in this complex polymer.
items:
anyOf:
- $ref: '#/components/schemas/NucleotideSimplePolymer'
- $ref: '#/components/schemas/ChemSimplePolymer'
- $ref: '#/components/schemas/PeptideSimplePolymer'
description: Union of NucleotideSimplePolymer, ChemSimplePolymer, PeptideSimplePolymer
discriminator:
propertyName: __typename
type: array
type: object
ListItemDocumentContent:
description: 'Represents a single list item within notebook or document content.
List items store their marker style, rich text, and indentation for ordered, unordered, and checklist blocks.'
properties:
__typename:
type: string
formats:
items:
$ref: '#/components/schemas/TextFormat'
type: array
indentation:
type: integer
links:
items:
$ref: '#/components/schemas/LinkSpan'
type: array
listTy
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-documentpart-api-openapi.yml