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 Entry API
version: 2.0.0
description: 'An Entry is the core document type in Benchling''s Electronic Lab Notebook (ELN), used
by scientists to record experimental work and observations. Entries are organized into
sections (days) containing various content types such as text, tables, file attachments,
and structured data tables for results. Entries support rich collaboration features
including authorship tracking, review workflows (see `Review` and `ReviewProcess`),
access control through Projects and Folders, and can be linked to Studies. Entries may
optionally conform to an `EntrySchema` that defines custom fields. They can be created
from scratch or from an `EntryTemplate` to ensure consistent structure. Entry mutation
endpoints are currently in closed LA.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'An Entry is the core document type in Benchling''s Electronic Lab Notebook (ELN), used
by scientists to record experimental work and observations. Entries are organized into
sections (days) containing various content types such as text, tables, file attachments,
and structured data tables for results. Entries support rich collaboration features
including authorship tracking, review workflows (see `Review` and `ReviewProcess`),
access control through Projects and Folders, and can be linked to Studies. Entries may
optionally conform to an `EntrySchema` that defines custom fields. They can be created
from scratch or from an `EntryTemplate` to ensure consistent structure. Entry mutation
endpoints are currently in closed LA.'
name: Entry
x-bnch-core-type: Entry
x-bnch-organization: Benchling
paths:
/entry:
post:
description: Create Entry.
operationId: Entry.Create
parameters:
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateEntryInput'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Entry'
description: Created
'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: Create Entry
tags:
- Entry
x-bnch-rate-limit-tier: 4
/entry/items:
get:
description: List Entry items.
operationId: Entry.List
parameters:
- $ref: '#/components/parameters/archiveReason.anyOf'
- $ref: '#/components/parameters/archived.anyOf'
- $ref: '#/components/parameters/authors.anyOf'
- $ref: '#/components/parameters/createdAt.gt'
- $ref: '#/components/parameters/createdAt.gte'
- $ref: '#/components/parameters/createdAt.lt'
- $ref: '#/components/parameters/createdAt.lte'
- $ref: '#/components/parameters/creator.anyOf'
- $ref: '#/components/parameters/id.anyOf'
- $ref: '#/components/parameters/mentionedIn.anyOf'
- $ref: '#/components/parameters/modifiedAt.gt'
- $ref: '#/components/parameters/modifiedAt.gte'
- $ref: '#/components/parameters/modifiedAt.lt'
- $ref: '#/components/parameters/modifiedAt.lte'
- $ref: '#/components/parameters/name.anyOf'
- $ref: '#/components/parameters/name.anyOf.caseSensitive'
- $ref: '#/components/parameters/nextToken'
- $ref: '#/components/parameters/omit'
- $ref: '#/components/parameters/pageSize'
- $ref: '#/components/parameters/returning'
- $ref: '#/components/parameters/schema.anyOf'
- $ref: '#/components/parameters/schema.eq'
- description: '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.'
in: query
name: sort
schema:
default: modifiedAt:desc
enum:
- createdAt:asc
- createdAt:desc
- 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/EntryPaginatedList'
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 Entry items
tags:
- Entry
x-bnch-rate-limit-tier: 4
/entry/{entry_id}:
get:
description: Get a single Entry by ID.
operationId: Entry.Get
parameters:
- description: ID of the Entry.
in: path
name: entry_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/Entry'
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 Entry by ID
tags:
- Entry
x-bnch-rate-limit-tier: 5
patch:
description: Update Entry.
operationId: Entry.Update
parameters:
- description: ID of the Entry.
in: path
name: entry_id
required: true
schema:
type: string
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateEntryInput'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Entry'
description: OK
'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: Update Entry
tags:
- Entry
x-bnch-rate-limit-tier: 4
/entry/{entry_id}/applicable-review-processes/items:
get:
description: List ReviewProcess items.
operationId: Entry.applicableReviewProcesses.List
parameters:
- description: ID of the Entry.
in: path
name: entry_id
required: true
schema:
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/ReviewProcessUnpaginatedList'
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 ReviewProcess items
tags:
- Entry
x-bnch-rate-limit-tier: 4
/entry/{entry_id}/authors/items:
get:
description: List Principal items.
operationId: Entry.authors.List
parameters:
- description: ID of the Entry.
in: path
name: entry_id
required: true
schema:
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/PrincipalUnpaginatedList'
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 Principal items
tags:
- Entry
x-bnch-rate-limit-tier: 4
/entry/{entry_id}/parts/items:
get:
description: List DocumentPart items.
operationId: Entry.parts.List
parameters:
- $ref: '#/components/parameters/nextToken'
- $ref: '#/components/parameters/pageSize'
- description: ID of the Entry.
in: path
name: entry_id
required: true
schema:
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:
- Entry
x-bnch-rate-limit-tier: 4
/entry:batch-create:
post:
description: Batch create Entry synchronously in one transaction. Maximum 25 items per request.
operationId: Entry.BatchCreate
parameters:
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/CreateEntryInput'
maxItems: 25
minItems: 1
type: array
required:
- items
type: object
responses:
'201':
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Entry'
type: array
required:
- items
type: object
description: Created
'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: Batch create Entry
tags:
- Entry
x-bnch-rate-limit-tier: 3
/entry:batch-update:
patch:
description: Batch update Entry synchronously in one transaction. Maximum 25 items per request.
operationId: Entry.BatchUpdate
parameters:
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/UpdateEntryInputWithPathParams'
maxItems: 25
minItems: 1
type: array
required:
- items
type: object
responses:
'200':
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Entry'
type: array
required:
- items
type: object
description: OK
'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: Batch update Entry
tags:
- Entry
x-bnch-rate-limit-tier: 3
/entry:bulk-create:
post:
description: Bulk create Entry.
operationId: Entry.BulkCreate
parameters:
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkImport'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: Task started
'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: Bulk create Entry
tags:
- Entry
x-bnch-rate-limit-tier: 2
/entry:bulk-update:
patch:
description: Bulk update Entry.
operationId: Entry.BulkUpdate
parameters:
- description: Set to true to access beta operations via /api/v3.
in: header
name: EARLY-ACCESS
required: false
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkImport'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: Task started
'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: Bulk update Entry
tags:
- Entry
x-bnch-rate-limit-tier: 2
webhooks:
v3.entry.created:
post:
description: Sent to Benchling Apps subscribed to `v3.entry.created` when a Entry they can access is created.
operationId: Entry.Created
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/EntryCreatedWebhookEnvelopeV3'
description: The `v3.entry.created` event.
required: true
responses:
'200':
description: Return a 200 status code to acknowledge receipt of the webhook.
summary: Entry created
tags:
- Entry
components:
schemas:
EntryCreatedWebhookV3:
allOf:
- $ref: '#/components/schemas/V3EventBase'
- properties:
type:
description: The event type.
enum:
- v3.entry.created
type: string
required:
- type
type: object
description: Message body of a `v3.entry.created` event.
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
CreateResultTableInput:
additionalProperties: false
properties:
contentType:
enum:
- result_table
type: string
resultSchemaId:
type: string
required:
- contentType
- resultSchemaId
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
ReviewRef:
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
WebhookApp:
description: The Benchling App the webhook was delivered to.
properties:
id:
description: API ID of the app.
examples:
- app_1jdbvuo2740aslk
type: string
required:
- id
type: object
AppInstallation:
description: 'Represents an installed Benchling App on a tenant, created from an `AppDefinitionVersion`.
App installations store tenant-specific configuration values and feature bindings. As a
Principal, app installations can be attributed as actors for API operations and auditing.'
properties:
__typename:
type: string
archiveReason:
type:
- 'null'
- string
archived:
type: boolean
configurationValues:
format: uri
type: string
createdAt:
format: datetime
type:
- 'null'
- string
creator:
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
featureValues:
items:
$ref: '#/components/schemas/AssayRunFeatureValue'
type: array
id:
type: string
modifiedAt:
format: datetime
type:
- 'null'
- string
name:
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
User:
description: 'Represents a human user in Benchling who can log in, perform actions, and own data.
Users belong to one or more Organizations and may be members of Teams within those
organizations. As an Owner, users can own Projects, Folders, and other resources.
As a Principal, users can be assigned as reviewers, authors, or collaborators on
various items. Users have attributes like email and username for identification.
Users are distinct from `ServicePrincipal`, which represents non-human service
accounts used for integrations.'
properties:
__typename:
type: string
createdAt:
format: datetime
type: string
email:
type: string
id:
type: string
lastSeen:
format: datetime
type:
- 'null'
- string
modifiedAt:
format: datetime
type: string
name:
type:
- 'null'
- string
status:
enum:
- ACTIVE
- SUSPENDED
type: string
username:
type: string
type: object
InsertDocumentPartsInput:
additionalProperties: false
properties:
coordinates:
$ref: '#/components/schemas/InsertCoordinates'
operationType:
enum:
- insert
type: string
parts:
items:
$ref: '#/components/schemas/DocumentContentInput'
type: array
version:
type: string
required:
- operationType
- version
- coordinates
- parts
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
AppConfigWorkflowTaskSchemaOutput:
description: Defines the output field structure for a workflow task schema co
# --- truncated at 32 KB (156 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-entry-api-openapi.yml