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 Well Plate API
version: 2.0.0
description: 'A WellPlate is a multi-well plate in Benchling''s inventory system where wells are
permanently fixed to the plate structure. This is the standard plate type for laboratory
multi-well formats such as 96-well, 384-well, and 1536-well plates used in high-throughput
screening, PCR, and other assay workflows. The plate''s grid dimensions are defined by its
WellPlateSchema, and each well (see WellPlatePosition) can contain samples, track quantities,
and be assigned experimental roles. WellPlates can be stored in Locations (via parentStorage),
associated with Studies, and identified by barcode. The plateRecords field tracks the history
of transfers and annotations performed on the plate (see PlateRecord). Unlike MatrixPlate
where containers can be inserted or removed, WellPlate wells are integral to the plate.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A WellPlate is a multi-well plate in Benchling''s inventory system where wells are
permanently fixed to the plate structure. This is the standard plate type for laboratory
multi-well formats such as 96-well, 384-well, and 1536-well plates used in high-throughput
screening, PCR, and other assay workflows. The plate''s grid dimensions are defined by its
WellPlateSchema, and each well (see WellPlatePosition) can contain samples, track quantities,
and be assigned experimental roles. WellPlates can be stored in Locations (via parentStorage),
associated with Studies, and identified by barcode. The plateRecords field tracks the history
of transfers and annotations performed on the plate (see PlateRecord). Unlike MatrixPlate
where containers can be inserted or removed, WellPlate wells are integral to the plate.'
name: WellPlate
x-bnch-core-type: WellPlate
x-bnch-organization: Benchling
paths:
/well-plate:
post:
description: Create WellPlate.
operationId: WellPlate.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/CreateWellPlateInput'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/WellPlate'
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 WellPlate
tags:
- WellPlate
x-bnch-rate-limit-tier: 4
/well-plate/items:
get:
description: List WellPlate items.
operationId: WellPlate.List
parameters:
- $ref: '#/components/parameters/archiveReason.anyOf'
- $ref: '#/components/parameters/archived.anyOf'
- $ref: '#/components/parameters/barcode.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/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/parentStorage.eq'
- $ref: '#/components/parameters/returning'
- 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/WellPlatePaginatedList'
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 WellPlate items
tags:
- WellPlate
x-bnch-rate-limit-tier: 4
/well-plate/{well_plate_id}:
get:
description: Get a single WellPlate by ID.
operationId: WellPlate.Get
parameters:
- description: ID of the WellPlate.
in: path
name: well_plate_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/WellPlate'
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 WellPlate by ID
tags:
- WellPlate
x-bnch-rate-limit-tier: 5
patch:
description: Update WellPlate.
operationId: WellPlate.Update
parameters:
- description: ID of the WellPlate.
in: path
name: well_plate_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/UpdateWellPlateInput'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/WellPlate'
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 WellPlate
tags:
- WellPlate
x-bnch-rate-limit-tier: 4
/well-plate/{well_plate_id}/positions/items:
get:
description: List WellPlatePosition items.
operationId: WellPlate.positions.List
parameters:
- description: ID of the WellPlate.
in: path
name: well_plate_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/WellPlatePositionUnpaginatedList'
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 WellPlatePosition items
tags:
- WellPlate
x-bnch-rate-limit-tier: 4
/well-plate:batch-create:
post:
description: Batch create WellPlate synchronously in one transaction. Maximum 10 items per request.
operationId: WellPlate.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/CreateWellPlateInput'
maxItems: 10
minItems: 1
type: array
required:
- items
type: object
responses:
'201':
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/WellPlate'
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 WellPlate
tags:
- WellPlate
x-bnch-rate-limit-tier: 3
/well-plate:batch-update:
patch:
description: Batch update WellPlate synchronously in one transaction. Maximum 10 items per request.
operationId: WellPlate.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/UpdateWellPlateInputWithPathParams'
maxItems: 10
minItems: 1
type: array
required:
- items
type: object
responses:
'200':
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/WellPlate'
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 WellPlate
tags:
- WellPlate
x-bnch-rate-limit-tier: 3
/well-plate:bulk-create:
post:
description: Bulk create WellPlate.
operationId: WellPlate.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 WellPlate
tags:
- WellPlate
x-bnch-rate-limit-tier: 2
/well-plate:bulk-update:
patch:
description: Bulk update WellPlate.
operationId: WellPlate.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 WellPlate
tags:
- WellPlate
x-bnch-rate-limit-tier: 2
components:
schemas:
UpdateWellPlateInput:
additionalProperties: false
properties:
archiveReason:
description: Why the plate is archived
type: string
archived:
description: Whether the plate is archived
type: boolean
barcode:
description: Barcode of the plate
type: string
name:
description: Name of the plate; defaults to barcode if name is not provided
type: string
parentStorageId:
type:
- 'null'
- string
projectId:
type:
- 'null'
- string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
description: Schema field values that belong to the plate
type: object
type: object
FieldValueInput:
additionalProperties: false
properties:
value:
$ref: '#/components/schemas/AnyType'
required:
- value
type: object
UpdateWellPlateInputWithPathParams:
additionalProperties: false
properties:
archiveReason:
description: Why the plate is archived
type: string
archived:
description: Whether the plate is archived
type: boolean
barcode:
description: Barcode of the plate
type: string
id:
type: string
name:
description: Name of the plate; defaults to barcode if name is not provided
type: string
parentStorageId:
type:
- 'null'
- string
projectId:
type:
- 'null'
- string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
description: Schema field values that belong to the plate
type: object
required:
- id
type: object
AnyType: {}
GridCoordinates:
description: Read model representing a fillable position in a box or plate.
properties:
__typename:
type: string
column:
description: The 0-indexed column index of the position
type: integer
index:
description: 'The 1-indexed position determined by counting across rows.
For example, for a six-well plate:
+---+---+---+
| 1 | 2 | 3 |
+---+---+---+
| 4 | 5 | 6 |
+---+---+---+'
type: integer
position:
description: 'The alphanumeric position, where rows are indexed alphabetically and columns are indexed numerically,
starting from "A1"'
type: string
row:
description: The 0-indexed row index of the position
type: integer
type: object
WellPlate:
allOf:
- $ref: '#/components/schemas/IWellPlate'
- description: 'A WellPlate is a multi-well plate in Benchling''s inventory system where wells are
permanently fixed to the plate structure. This is the standard plate type for laboratory
multi-well formats such as 96-well, 384-well, and 1536-well plates used in high-throughput
screening, PCR, and other assay workflows. The plate''s grid dimensions are defined by its
WellPlateSchema, and each well (see WellPlatePosition) can contain samples, track quantities,
and be assigned experimental roles. WellPlates can be stored in Locations (via parentStorage),
associated with Studies, and identified by barcode. The plateRecords field tracks the history
of transfers and annotations performed on the plate (see PlateRecord). Unlike MatrixPlate
where containers can be inserted or removed, WellPlate wells are integral to the plate.'
properties:
__typename:
type: string
creator:
$ref: '#/components/schemas/PrincipalRef'
description: The user who created the plate
positions:
description: The wells of the plate
format: uri
type: string
schemaFields:
description: Schema field values that belong to the plate
oneOf:
- items:
$ref: '#/components/schemas/SchemaFieldValue'
type: array
- type: 'null'
type: object
WellPlateSchemaRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
DateValue:
description: A type that represents date values.
properties:
__typename:
type: string
value:
description: The date value.
format: date
type: string
type: object
BooleanValue:
description: A type that represents boolean values.
properties:
__typename:
type: string
value:
description: The boolean value.
type: boolean
type: object
ProjectRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
ObjectLinkValue:
description: A type that represents links to other objects.
properties:
__typename:
type: string
value:
$ref: '#/components/schemas/ObjectRef'
description: The object that this value links to, or an Inaccessible object if not found with the current permission set.
type: object
WellPlatePositionUnpaginatedList:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/WellPlatePosition'
type: array
type: object
WellPlatePosition:
description: 'Represents a single well within a WellPlate, functioning as a fixed container at a
specific grid position. Each WellPlatePosition has coordinates identifying its row
and column, can hold sample contents (see ContainerContent), and tracks quantity as
a Measurement. Wells can be assigned an ExperimentalRole for assay organization and
support freeze/thaw tracking (see FreezeThawInfo) and expiration tracking (see
ExpirationInfo) when enabled on the well''s ContainerSchema. Unlike containers in a
MatrixPlate, WellPlatePositions are permanent parts of the plate structure and cannot
be removed or repositioned. Wells are accessed through the parent WellPlate''s positions
field.'
properties:
__typename:
type: string
contents:
description: Well contents of the well plate.
items:
$ref: '#/components/schemas/ContainerContent'
type: array
coordinates:
$ref: '#/components/schemas/GridCoordinates'
description: Coordinates of the current position within the well plate.
createdAt:
description: When the well plate was created.
format: datetime
type: string
expirationInfo:
$ref: '#/components/schemas/ExpirationInfo'
description: Expiration info for the container.
id:
description: The ID of the container representing the well at this plate position.
type: string
modifiedAt:
description: When the well plate was last modified.
format: datetime
type: string
name:
description: The name of the container representing the well at this position.
type: string
quantity:
description: Quantity of a well. Supports mass, volume, and other quantities.
oneOf:
- $ref: '#/components/schemas/Measurement'
- type: 'null'
role:
oneOf:
- $ref: '#/components/schemas/ExperimentalRole'
- type: 'null'
schema:
$ref: '#/components/schemas/ContainerSchemaRef'
description: The container schema used by wells in the well plate.
type: object
CreateWellPlateInput:
additionalProperties: false
properties:
barcode:
description: Barcode of the plate
type: string
name:
description: Name of the plate; defaults to barcode if name is not provided
type: string
parentStorageId:
type: string
projectId:
type: string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
description: Schema field values that belong to the plate
type: object
schemaId:
type: string
required:
- schemaId
type: object
ExperimentalRole:
description: 'Represents the complete experimental designation of a well or container within an assay,
combining a primary role (see PrimaryExperimentalRole), replicate group number, and
optional subrole. The group field identifies replicate sets: wells with the same primary
role and group number are treated as technical replicates for statistical analysis. The
subrole field provides additional categorization for controls (e.g., POSITIVE, NEGATIVE,
MAXIMUM, MINIMUM); only CONTROL primary roles may have subroles. ExperimentalRole is
used in plate-based workflows to define experimental layouts (see PlateMapPosition) and
annotate wells in FixedPlate and Container objects.'
properties:
__typename:
type: string
group:
description: Role group (aka replicate id)
type: integer
primaryRole:
description: Primary role
enum:
- CONTROL
- SAMPLE
- BLANK
- STANDARD
type: string
subrole:
description: Subrole, used to differentiate different sub types of a role (e.g. positive control)
type:
- 'null'
- 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
InternalServerError:
properties:
detail:
type:
- 'null'
- string
- object
errorId:
type: string
instance:
type: string
status:
type: integer
title:
type:
- 'null'
- string
type:
type: string
required:
- type
- title
- detail
- status
- instance
type: object
DecimalValue:
description: A type that represents decimal value as strings.
properties:
__typename:
type: string
numericValue:
deprecated: true
description: Deprecated. The float representation of the decimal value.
type:
- 'null'
- number
value:
description: The decimal value in a string representation
type:
- 'null'
- string
type: object
AsyncTaskLink:
properties:
pollingUri:
format: uri
type: string
taskId:
type: string
type: object
ArrayValue:
description: A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns).
properties:
__typename:
type: string
value:
items:
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'
description: Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue
discriminator:
propertyName: __typename
type: array
type: object
ContainerContent:
description: 'Represents a biological or chemical entity stored within a Container or well. Each
ContainerContent links an Entity (such as a DNA sequence, protein, or custom entity)
to its storage location, along with an optional concentration measurement. The
timestamps track when the entity was first placed in the container and when the
concentration was last modified. A container can hold multiple ContainerContent
items representing different entities or samples stored together.'
properties:
__typename:
type: string
concentration:
description: Concentration of the entity in the container.
oneOf:
- $ref: '#/components/schemas/Measurement'
- type: 'null'
createdAt:
description: When the container was first filled with this entity.
format: datetime
type: string
entity:
description: The entity in the container.
oneOf:
- $ref: '#/components/schemas/EntityRef'
- type: 'null'
modifiedAt:
description: When the entity was last added to this container or the concentration was last changed.
format: datetime
type: string
type: object
Measurement:
description: 'Represents a quantity with an associated unit of measurement within Benchling''s inventory
system. Measurements are used throughout inventory to track container volumes, sample
masses, concentrations, and other quantitative values. Each Measurement pairs a numeric
value with a Unit (see Unit) to provide context-aware quantity handling. For example,
a container might have a Measurement of 500 uL for its volume. Unlike ContainerQuantity
which provides a simpler representation, Measurement supports the full Unit system with
dimensional conversions.'
properties:
__typename:
type: string
unit:
oneOf:
- $ref: '#/components/schemas/UnitRef'
- type: 'null'
value:
type:
- 'null'
- number
type: object
LocationRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
BulkImport:
example:
fileId: scrfile_jdf8BV24kLmN
properties:
fileId:
description: The API ID of the scratch file (`scrfile_XXXXXXXX`) containing the items to import. The referenced file must be a scratch file whose upload has completed successfully.
type: string
required:
- fileId
type: object
ExpirationInfo:
description: 'Provides expiration tracking for inventory items such as containers and their
contents. The expirationDate may be explicitly set on the container or inherited
from the stored entity''s properties. The isExpired flag is a computed convenience
field that returns true if the current date is past the expiration date. Items
without an expiration date are considered non-expiring (isExpired returns false).'
properties:
__typename:
type: string
expirationDate:
description: Expiration date of the item, potentially inherited from the contents or overridden.
format: datetime
type:
- 'null'
- string
isExpired:
description: Whether the item is past its expiration date. Items without an expiration date return False.
type: boolean
type: object
IWellPlate:
properties:
__typename:
type: string
archiveReason:
description: Why the plate is arc
# --- truncated at 32 KB (43 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-wellplate-api-openapi.yml