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 Plate API
version: 2.0.0
description: 'A Plate is a legacy unified type representing both well plates and tube racks in
Benchling''s inventory system. The type field (see PlateType) indicates whether this
is a FIXED_PLATE (wells permanently attached, like 96-well or 384-well plates) or a
MATRIX_PLATE (removable containers in a grid, like tube racks). For new integrations,
prefer using the specific FixedPlate and MatrixPlate types which provide clearer
semantics and type-specific fields. Plates can be stored in Locations (via parentStorage),
associated with Studies, and identified by barcode. The wells field returns Container
objects representing the plate positions.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A Plate is a legacy unified type representing both well plates and tube racks in
Benchling''s inventory system. The type field (see PlateType) indicates whether this
is a FIXED_PLATE (wells permanently attached, like 96-well or 384-well plates) or a
MATRIX_PLATE (removable containers in a grid, like tube racks). For new integrations,
prefer using the specific FixedPlate and MatrixPlate types which provide clearer
semantics and type-specific fields. Plates can be stored in Locations (via parentStorage),
associated with Studies, and identified by barcode. The wells field returns Container
objects representing the plate positions.'
name: Plate
x-bnch-core-type: Plate
x-bnch-organization: Benchling
paths:
/plate/items:
get:
description: List Plate items.
operationId: Plate.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/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/parentStorage.eq'
- $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/PlatePaginatedList'
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 Plate items
tags:
- Plate
x-bnch-rate-limit-tier: 4
/plate/{plate_id}:
get:
description: Get a single Plate by ID.
operationId: Plate.Get
parameters:
- description: ID of the Plate.
in: path
name: 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/Plate'
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 Plate by ID
tags:
- Plate
x-bnch-rate-limit-tier: 5
/plate/{plate_id}/wells/items:
get:
description: List Container items.
operationId: Plate.wells.List
parameters:
- description: ID of the Plate.
in: path
name: 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/ContainerUnpaginatedList'
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 Container items
tags:
- Plate
x-bnch-rate-limit-tier: 4
components:
parameters:
parentStorage.eq:
description: ID of a location. Restricts results to those located in the specified inventory.
in: query
name: parentStorage.eq
schema:
type: string
pageSize:
description: Number of results to return. Defaults to 50, maximum of 100.
in: query
name: pageSize
schema:
type: integer
createdAt.gte:
description: 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.
in: query
name: createdAt.gte
schema:
format: datetime
type: string
modifiedAt.gt:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified after the specified time. e.g. > 2017-04-30.
in: query
name: modifiedAt.gt
schema:
format: datetime
type: string
barcode.anyOf:
description: Restricts results to those matching any of the specified barcodes. Fails and reports any invalid barcodes. Comma-separated list.
explode: false
in: query
name: barcode.anyOf
schema:
items:
type: string
maxItems: 100
type: array
modifiedAt.lte:
description: 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.
in: query
name: modifiedAt.lte
schema:
format: datetime
type: string
id.anyOf:
description: Restricts results to those matching any of the specified IDs. Comma-separated list.
explode: false
in: query
name: id.anyOf
schema:
items:
type: string
maxItems: 100
type: array
modifiedAt.lt:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified before the specified time. e.g. < 2017-04-30.
in: query
name: modifiedAt.lt
schema:
format: datetime
type: string
creator.anyOf:
description: Restricts results to those created by any of the specified user IDs. Comma-separated list.
explode: false
in: query
name: creator.anyOf
schema:
items:
type: string
maxItems: 100
type: array
mentionedIn.anyOf:
description: Restricts results to items mentioned in entries matching any of the specified entry IDs. Comma-separated list.
explode: false
in: query
name: mentionedIn.anyOf
schema:
items:
type: string
maxItems: 100
type: array
createdAt.gt:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created after the specified time. e.g. > 2017-04-30.
in: query
name: createdAt.gt
schema:
format: datetime
type: string
modifiedAt.gte:
description: 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.
in: query
name: modifiedAt.gte
schema:
format: datetime
type: string
schema.anyOf:
description: Restricts results to those that match any of the specified schema IDs. Use only one `schema` filter arg at a time. Comma-separated list.
explode: false
in: query
name: schema.anyOf
schema:
items:
type: string
maxItems: 100
type: array
createdAt.lt:
description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created before the specified time. e.g. < 2017-04-30.
in: query
name: createdAt.lt
schema:
format: datetime
type: string
archiveReason.anyOf:
description: 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.
explode: false
in: query
name: archiveReason.anyOf
schema:
items:
type: string
maxItems: 10
type: array
returning:
description: Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit.
explode: false
in: query
name: returning
schema:
items:
type: string
type: array
archived.anyOf:
description: If true, returns archived items. If false, returns unarchived items. If both true and false, returns archived and unarchived items. Comma-separated list.
explode: false
in: query
name: archived.anyOf
schema:
items:
type: boolean
maxItems: 2
type: array
nextToken:
description: Token for pagination
in: query
name: nextToken
schema:
type: string
name.anyOf:
description: 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.
explode: false
in: query
name: name.anyOf
schema:
items:
type: string
maxItems: 100
type: array
name.anyOf.caseSensitive:
description: 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.
explode: false
in: query
name: name.anyOf.caseSensitive
schema:
items:
type: string
maxItems: 100
type: array
omit:
description: Comma-separated list of top-level fields to omit from each returned item. Cannot overlap with returning.
explode: false
in: query
name: omit
schema:
items:
type: string
type: array
schema.eq:
description: Single schema ID. Restricts results to those that match the specified schema exactly. Use only one `schema` filter arg at a time.
in: query
name: schema.eq
schema:
type: string
createdAt.lte:
description: 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.
in: query
name: createdAt.lte
schema:
format: datetime
type: string
schemas:
CheckoutRecord:
description: 'Tracks the checkout status of an inventory item such as a Container. When laboratory
samples need to be temporarily removed from storage (e.g., for an experiment), users
can check them out, optionally adding a comment and assigning responsibility to a
user or team (see Assignee). The record captures when the status was last modified.
This enables sample tracking workflows and prevents conflicts when multiple users
need access to the same samples.'
properties:
__typename:
type: string
assignee:
description: Union of User, Team
oneOf:
- $ref: '#/components/schemas/ObjectRef'
- type: 'null'
comment:
type:
- 'null'
- string
modifiedAt:
format: datetime
type:
- 'null'
- string
status:
enum:
- AVAILABLE
- RESERVED
- CHECKED_OUT
- null
type:
- 'null'
- string
type: object
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
DateValue:
description: A type that represents date values.
properties:
__typename:
type: string
value:
description: The date value.
format: date
type: string
type: object
IContainer:
properties:
__typename:
type: string
archiveReason:
type:
- 'null'
- string
archived:
type: boolean
barcode:
type:
- 'null'
- string
checkoutRecord:
$ref: '#/components/schemas/CheckoutRecord'
contents:
items:
$ref: '#/components/schemas/ContainerContent'
type: array
coordinates:
description: Coordinates of the container within its contained grid, if it is contained within a grid.
oneOf:
- $ref: '#/components/schemas/GridCoordinates'
- type: 'null'
createdAt:
format: datetime
type: string
expirationInfo:
$ref: '#/components/schemas/ExpirationInfo'
description: Expiration info for the container.
gridNumber:
deprecated: true
description: Please use coordinates.index
type:
- 'null'
- number
gridPosition:
deprecated: true
description: Please use coordinates.position
type:
- 'null'
- string
id:
type: string
modifiedAt:
format: datetime
type: string
name:
type: string
parentStorage:
description: Union of Box, Plate, Location
oneOf:
- $ref: '#/components/schemas/ObjectRef'
- type: 'null'
parentStorageSchema:
description: Union of BoxSchema, PlateSchema, LocationSchema
oneOf:
- $ref: '#/components/schemas/ObjectRef'
- type: 'null'
project:
oneOf:
- $ref: '#/components/schemas/ProjectRef'
- type: 'null'
quantity:
description: 'Quantity of a container, well, or transfer. 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'
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
Plate:
allOf:
- $ref: '#/components/schemas/IPlate'
- description: 'A Plate is a legacy unified type representing both well plates and tube racks in
Benchling''s inventory system. The type field (see PlateType) indicates whether this
is a FIXED_PLATE (wells permanently attached, like 96-well or 384-well plates) or a
MATRIX_PLATE (removable containers in a grid, like tube racks). For new integrations,
prefer using the specific FixedPlate and MatrixPlate types which provide clearer
semantics and type-specific fields. Plates can be stored in Locations (via parentStorage),
associated with Studies, and identified by barcode. The wells field returns Container
objects representing the plate positions.'
properties:
__typename:
type: string
creator:
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
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
IPlate:
properties:
__typename:
type: string
archiveReason:
type:
- 'null'
- string
archived:
type: boolean
availableCapacity:
description: The number of available positions in a matrix plate. Null for well plates.
type:
- 'null'
- integer
barcode:
description: Barcode of the plate
type:
- 'null'
- string
createdAt:
description: DateTime the plate was created
format: datetime
type:
- 'null'
- string
id:
description: ID of the plate
type: string
modifiedAt:
description: DateTime the plate was last modified
format: datetime
type:
- 'null'
- string
name:
description: Name of the plate, defaults to barcode if name is not provided.
type:
- 'null'
- string
occupiedCapacity:
description: The number of containers currently in a matrix plate. Null for well plates.
type:
- 'null'
- integer
parentStorage:
description: Containing parent storage.
oneOf:
- $ref: '#/components/schemas/LocationRef'
- type: 'null'
project:
oneOf:
- $ref: '#/components/schemas/ProjectRef'
- type: 'null'
schema:
oneOf:
- $ref: '#/components/schemas/PlateSchemaRef'
- type: 'null'
totalCapacity:
description: 'The total capacity of a matrix plate (i.e. how many containers it can store).
Null for well plates.'
type:
- 'null'
- integer
type:
enum:
- MATRIX_PLATE
- FIXED_PLATE
- null
type:
- 'null'
- string
wells:
description: Well contents of the plate, keyed by position string (eg. "A1").
oneOf:
- format: uri
type: string
- type: 'null'
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
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
PlatePaginatedList:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Plate'
type: array
nextToken:
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
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
PrincipalRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
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
ContainerSchemaRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
ContainerUnpaginatedList:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Container'
type: array
type: object
ObjectRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
PlateSchemaRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
TextValue:
description: A type that represents text (string) values.
properties:
__typename:
type: string
value:
description: The text value. It may or may not be an empty string.
type: string
type: object
JsonValue:
description: A type that represents JSON values.
properties:
__typename:
type: string
value:
description: The JSON value.
type: object
type: object
Container:
allOf:
- $ref: '#/components/schemas/IContainer'
- description: 'A Container is a physical vessel (such as a tube, vial, or cryotube) that holds
biological or chemical samples in Benchling''s inventory system. Containers track
their contents (see ContainerContent), quantity, location within storage (via
parentStorage which can be a Box, Plate, or Location), and lifecycle information
including expiration and freeze-thaw cycles. Each container has a barcode for
physical identification and conforms to a ContainerSchema that defines its type
and schema fields. Containers support ch
# --- truncated at 32 KB (36 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-plate-api-openapi.yml