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 checkout tracking (see CheckoutRecord) and can be associated with Studies. Also known as "tubes" or "sample containers" in laboratory contexts.' properties: __typename: type: string creator: $ref: '#/components/schemas/PrincipalRef' schemaFields: oneOf: - items: $ref: '#/components/schemas/SchemaFieldValue' type: array - type: 'null' 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 IntegerValue: description: A type that represents integer values. properties: __typename: type: string value: description: The integer value. type: integer type: object SchemaFieldDefinitionRef: properties: __typename: type: string id: format: api_id type: string type: object ObjectLinkListValue: description: A type that represents a list of links to other objects. properties: __typename: type: string value: description: The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set. items: $ref: '#/components/schemas/ObjectRef' description: Union of AaSequence, Box, Container, CustomEntity, DnaSequence, DropdownOption, Entry, Location, Mixture, Molecule, Plate, Result, RnaSequence, Run, DnaOligo, RnaOligo type: array type: object UnitRef: properties: __typename: type: string id: format: api_id type: string type: object GeneralError: properties: detail: type: - 'null' - string - object instance: type: string status: type: integer title: type: - 'null' - string type: type: string required: - type - title - detail - status - instance type: object EntityRef: properties: __typename: type: string id: format: api_id type: string type: object responses: TooManyRequests: content: application/problem+json: schema: $ref: '#/components/schemas/GeneralError' description: Too Many Requests NotFound: content: application/problem+json: schema: $ref: '#/components/schemas/GeneralError' description: Not Found BadRequest: content: application/problem+json: schema: $ref: '#/components/schemas/GeneralError' description: Bad Request Forbidden: content: application/problem+json: schema: $ref: '#/components/schemas/GeneralError' description: Forbidden InternalServerError: content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerError' description: Internal Server Error securitySchemes: basicApiKeyAuth: description: Use issued API key for standard access to the API scheme: basic type: http basicClientIdSecretAuth: description: Auth used as part of client credentials OAuth flow prior to receiving a bearer token. scheme: basic type: http oAuth: description: OAuth2 Client Credentials flow intended for service access flows: clientCredentials: scopes: {} tokenUrl: /oauth/token type: oauth2