openapi: 3.0.1
info:
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: Benchling AA Sequences Plates API
version: 2.0.0
description: 'AA Sequences are the working units of cells that make everything run (they help make structures, catalyze reactions and allow for signaling - a kind of internal cell communication). On Benchling, these are comprised of a string of amino acids and collections of other attributes, such as annotations.
'
servers:
- url: /api/v2
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: '
Plates are a structured inventory type, grids of wells that each function like containers. Plates come in two types: a traditional "fixed" type, where the wells cannot move, and a "matrix" type. A matrix plate has similar functionality to a box, where the containers inside can be moved around and removed altogether.
Plates are all associated with schemas, which define the type of the plate (e.g. "96 Well Plate") along with the fields that are tracked, the dimensions of the plate, and whether or not the plate is a matrix plate or a traditional well plate.
Like all inventory, every Plate has a barcode that is unique across the registry.
'
name: Plates
paths:
/plates:
get:
description: List plates
operationId: listPlates
parameters:
- description: 'Number of results to return. Defaults to 50, maximum of 100.
'
in: query
name: pageSize
schema:
default: 50
maximum: 100
minimum: 0
nullable: false
type: integer
- description: Token for pagination
in: query
name: nextToken
schema:
type: string
- description: 'Method by which to order search results. Valid sorts are barcode, name, modifiedAt, and createdAt. Optionally add :asc or :desc to specify ascending or descending order. Default is modifiedAt.
'
in: query
name: sort
schema:
default: modifiedAt:desc
enum:
- barcode
- barcode:asc
- barcode:desc
- modifiedAt
- modifiedAt:asc
- modifiedAt:desc
- name
- name:asc
- name:desc
- createdAt
- createdAt:asc
- createdAt:desc
nullable: false
type: string
- description: 'ID of a schema. Restricts results to those of the specified schema.
'
in: query
name: schemaId
schema:
type: string
- description: 'Filter based on schema field value (not display value). Restricts results to those with a field whose value matches the filter. For Integer, Float, and Date type fields, supports the >= and <= operators (but not < or >). If any schemaField filters are present, the schemaId param must also be present. Note that all operators must be separated from any values by a single space.
'
in: query
name: schemaFields
schema:
$ref: '#/components/schemas/SchemaFieldsQueryParam'
- description: 'Datetime, in RFC 3339 format. Supports the > and < operators. Time zone defaults to UTC. Restricts results to those created in the specified range. e.g. > 2017-04-30. Date ranges can be specified with the following nomenclature > YYYY-MM-DD AND <YYYY-MM-DD.
'
examples:
and-range:
summary: Filter for all models created within a certain range using the AND operator.
value: '> 2022-03-01 AND < 2022-04-01'
full-rfc-3339-format:
summary: Filter for created models using the full RFC 3339 format
value: '> 2020-12-31T21:07:14-05:00'
greater-than-example:
summary: Filter for all models created after a certain date
value: '> 2022-03-01'
in: query
name: createdAt
schema:
type: string
- description: 'Datetime, in RFC 3339 format. Supports the > and < operators. Time zone defaults to UTC. Restricts results to those modified in the specified range. e.g. > 2017-04-30. Date ranges can be specified with the following nomenclature > YYYY-MM-DD AND <YYYY-MM-DD.
'
examples:
and-range:
summary: Filter for all models modified within a certain range using the AND operator.
value: '> 2022-03-01 AND < 2022-04-01'
full-rfc-3339-format:
summary: Filter for modified models using the full RFC 3339 format
value: '> 2020-12-31T21:07:14-05:00'
greater-than-example:
summary: Filter for all models modified after a certain date
value: '> 2022-03-01'
in: query
name: modifiedAt
schema:
type: string
- description: Name of a plate. Restricts results to those with the specified name.
in: query
name: name
schema:
type: string
- description: 'Name substring of a plate. Restricts results to those with names that include the provided substring.
'
in: query
name: nameIncludes
schema:
type: string
- description: 'Only return plates that have the specified number of empty positions
'
in: query
name: emptyPositions
schema:
type: integer
- description: 'Only return plates that have greater-than or equal-to the specified number of empty positions.
'
in: query
name: emptyPositions.gte
schema:
type: integer
- description: 'Only return plates that have greater-than the specified number of empty positions.
'
in: query
name: emptyPositions.gt
schema:
type: integer
- description: 'Only return plates that have less-than or equal-to the specified number of empty positions.
'
in: query
name: emptyPositions.lte
schema:
type: integer
- description: 'Only return plates that have less-than the specified number of empty positions.
'
in: query
name: emptyPositions.lt
schema:
type: integer
- description: 'Only return plates that have the specified number of empty containers (containers without contents).
'
in: query
name: emptyContainers
schema:
type: integer
- description: 'Only return plates that have greater-than or equal-to the specified number of empty containers (containers without contents).
'
in: query
name: emptyContainers.gte
schema:
type: integer
- description: 'Only return plates that have greater-than the specified number of empty containers (containers without contents).
'
in: query
name: emptyContainers.gt
schema:
type: integer
- description: 'Only return plates that have less-than or equal-to the specified number of empty containers (containers without contents).
'
in: query
name: emptyContainers.lte
schema:
type: integer
- description: 'Only return plates that have less-than the specified number of empty containers (containers without contents).
'
in: query
name: emptyContainers.lt
schema:
type: integer
- description: 'ID of a location. Restricts results to those located in the specified inventory.
'
in: query
name: ancestorStorageId
schema:
type: string
- description: 'ID of a entity, or entity schema. Restricts results to those that hold containers with entities.
'
in: query
name: storageContentsId
schema:
type: string
- description: 'Comma-separated list of IDs of entities. Restricts results to those that hold containers with at least one of the specified entities.
'
in: query
name: storageContentsIds
schema:
type: string
- description: 'Archive reason. Restricts items to those with the specified archive reason. Use "NOT_ARCHIVED" to filter for unarchived plates. Use "ANY_ARCHIVED" to filter for archived plates regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived.
'
examples:
1_not_archived:
summary: Only include unarchived items (default).
value: NOT_ARCHIVED
2_archived_reason:
summary: Includes items archived for a specific reason.
value: Retired
3_any_archived:
summary: Includes items archived for any reason.
value: ANY_ARCHIVED
4_any_archived_or_not_archived:
summary: Includes both archived and unarchived items.
value: ANY_ARCHIVED_OR_NOT_ARCHIVED
in: query
name: archiveReason
schema:
type: string
- description: 'Comma-separated list of ids. Matches all of the provided IDs, or returns a 400 error that includes a list of which IDs are invalid.
'
in: query
name: ids
schema:
example: plt_xd4hj4eB,plt_xd4hj4C
type: string
- description: 'Comma-separated list of barcodes. Matches all of the provided barcodes, or returns a 400 error that includes a list of which barcodes are invalid.
'
in: query
name: barcodes
schema:
example: W102477,W102478
type: string
- description: 'Comma-separated list of names. Maximum of 100. Restricts results to those that match any of the specified names, case insensitive. Warning - this filter can be non-performant due to case insensitivity.
'
in: query
name: names.anyOf
schema:
example: MyName1,MyName2
type: string
- description: 'Comma-separated list of names. Maximum of 100. Restricts results to those that match any of the specified names, case sensitive.
'
in: query
name: names.anyOf.caseSensitive
schema:
example: MyName1,MyName2
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
'
in: query
name: returning
schema:
example: plates.id,plates.wells.*.webURL
type: string
- description: Comma separated list of users IDs
in: query
name: creatorIds
schema:
example: ent_a0SApq3z
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PlatesPaginatedList'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: List plates
tags:
- Plates
post:
description: Create a plate
operationId: createPlate
parameters:
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
'
in: query
name: returning
schema:
example: id,webURL
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PlateCreate'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Plate'
description: Created
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Create a plate
tags:
- Plates
/plates/{plate_id}:
get:
description: Get a plate
operationId: getPlate
parameters:
- in: path
name: plate_id
required: true
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
'
in: query
name: returning
schema:
example: id,webURL
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Plate'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
description: Not Found
summary: Get a plate
tags:
- Plates
patch:
description: Update a plate
operationId: updatePlate
parameters:
- in: path
name: plate_id
required: true
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
'
in: query
name: returning
schema:
example: id,webURL
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PlateUpdate'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Plate'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenError'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
description: Not Found
summary: Update a plate
tags:
- Plates
/plates:archive:
post:
description: Archive plates and any containers of the plates
operationId: archivePlates
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PlatesArchive'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PlatesArchivalChange'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenRestrictedSampleError'
description: Forbidden
summary: Archive plates
tags:
- Plates
/plates:bulk-get:
get:
description: BulkGet plates
operationId: bulkGetPlates
parameters:
- description: Comma-separated list of plate IDs.
in: query
name: plateIds
schema:
type: string
- description: Comma-separated list of plate barcodes.
explode: false
in: query
name: barcodes
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
'
in: query
name: returning
schema:
example: plates.id,plates.wells.*.webURL
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PlatesBulkGet'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
description: Not Found
summary: BulkGet plates
tags:
- Plates
/plates:unarchive:
post:
description: Unarchive plates and the containers that were archived along with them
operationId: unarchivePlates
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PlatesUnarchive'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/PlatesArchivalChange'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Unarchive plates
tags:
- Plates
components:
schemas:
Molecule:
additionalProperties: false
properties:
aliases:
description: Array of aliases.
items:
type: string
type: array
apiURL:
description: The canonical url of the Molecule in the API.
format: uri
readOnly: true
type: string
archiveRecord:
allOf:
- $ref: '#/components/schemas/ArchiveRecord'
nullable: true
authors:
items:
$ref: '#/components/schemas/UserSummary'
type: array
canonicalizedSmiles:
description: The canonicalized chemical structure in SMILES format.
example: Nc1nc(=O)n([H])cc1C1CC1
type: string
createdAt:
description: DateTime the Molecule was created.
format: date-time
readOnly: true
type: string
creator:
$ref: '#/components/schemas/UserSummary'
customFields:
allOf:
- $ref: '#/components/schemas/CustomFields'
description: Custom fields set on the Molecule.
entityRegistryId:
description: Registry ID of the Molecule if registered.
nullable: true
type: string
fields:
$ref: '#/components/schemas/Fields'
folderId:
description: ID of the folder that contains the Molecule.
nullable: true
type: string
id:
description: ID of the Molecule.
example: mol_bhuDUw9D
type: string
modifiedAt:
description: DateTime the Molecule was last modified.
format: date-time
readOnly: true
type: string
name:
description: Name of the Molecule.
type: string
originalSmiles:
description: The original chemical structure supplied by the user in SMILES format. Null if the user did not originally supply SMILES.
example: Nc1nc(=O)n([H])cc1C1CC1
nullable: true
type: string
registrationOrigin:
allOf:
- $ref: '#/components/schemas/RegistrationOrigin'
nullable: true
readOnly: true
registryId:
description: Registry the Molecule is registered in.
nullable: true
type: string
schema:
allOf:
- $ref: '#/components/schemas/SchemaSummary'
nullable: true
webURL:
description: URL of the Molecule.
example: https://benchling.com/benchling/f/lib_R8KcsjhW-molecules/mol_xCUXNVyG-molecule1/edit
format: uri
readOnly: true
type: string
type: object
ForbiddenRestrictedSampleError:
properties:
error:
allOf:
- $ref: '#/components/schemas/BaseError'
- properties:
invalidIds:
items:
type: string
type: array
type:
enum:
- invalid_request_error
type: string
- example:
invalidIds:
- Q6uhNZvw
- con_OwmERWGE
- con_zuDFhNvz
message: You're not a restricted sample user for some items.
type: invalid_request_error
userMessage: You're not a restricted sample user for some items.
type: object
PlatesArchivalChange:
description: 'IDs of all items that were archived or unarchived, grouped by resource type. This includes the IDs of plates along with any IDs of containers that were archived / unarchived.
'
properties:
containerIds:
items:
type: string
type: array
plateIds:
items:
type: string
type: array
type: object
EntityLabels:
properties:
entityRegistryId:
example: REAG000
nullable: true
type: string
id:
example: bfi_12345
type: string
name:
example: Deionized Water
type: string
type: object
Primer:
properties:
bases:
readOnly: true
type: string
bindPosition:
readOnly: true
type: integer
color:
readOnly: true
type: string
end:
description: 0-based exclusive end index. The end of the sequence is always represented as 0.
type: integer
name:
readOnly: true
type: string
oligoId:
type: string
overhangLength:
readOnly: true
type: integer
start:
description: 0-based inclusive start index.
type: integer
strand:
example: 1
type: integer
type: object
CustomEntity:
properties:
aliases:
items:
example: sBN000
type: string
type: array
apiURL:
description: The canonical url of the Custom Entity in the API.
example: https://benchling.com/api/v2/custom-entities/bfi_xCUXNVyG
format: uri
readOnly: true
type: string
archiveRecord:
allOf:
- $ref: '#/components/schemas/ArchiveRecord'
nullable: true
authors:
items:
$ref: '#/components/schemas/UserSummary'
type: array
createdAt:
example: '2017-04-18T05:54:56.247545+00:00'
format: date-time
readOnly: true
type: string
creator:
allOf:
- $ref: '#/components/schemas/UserSummary'
- readOnly: true
customFields:
$ref: '#/components/schemas/CustomFields'
entityRegistryId:
example: sBN000
nullable: true
type: string
fields:
$ref: '#/components/schemas/Fields'
folderId:
example: lib_R8KcsjhW
nullable: true
type: string
id:
example: bfi_xCUXNVyG
type: string
modifiedAt:
example: '2017-04-18T05:55:48.685345+00:00'
format: date-time
readOnly: true
type: string
name:
example: sBN000
type: string
registrationOrigin:
allOf:
- $ref: '#/components/schemas/RegistrationOrigin'
nullable: true
readOnly: true
registryId:
example: src_NetYd96a
nullable: true
type: string
schema:
allOf:
- $ref: '#/components/schemas/SchemaSummary'
example:
id: ts_EM122lfJ
name: Strain
nullable: true
url:
description: The path of the web URL, omitting the tenant domain
type: string
webURL:
example: https://benchling.com/benchling/f/R8KcsjhW-academic-registry/bfi-xCUXNVyG-sbn000/edit
readOnly: true
type: string
type: object
PlateCreate:
additionalProperties: false
properties:
barcode:
type: string
containerSchemaId:
type: string
fields:
$ref: '#/components/schemas/Fields'
name:
type: string
parentStorageId:
type: string
projectId:
type: string
schemaId:
type: string
wells:
additionalProperties:
properties:
barcode:
type: string
type: object
type: object
required:
- schemaId
type: object
RnaOligoWithEntityType:
allOf:
- $ref: '#/components/schemas/RnaOligo'
- properties:
entityType:
enum:
- rna_oligo
type: string
type: object
type: object
TeamSummary:
allOf:
- type: object
- properties:
id:
type: string
name:
type: string
- example:
id: team_5cjIguqc
name: Elion's Team
DnaSequenceWithEntityType:
allOf:
- $ref: '#/components/schemas/DnaSequence'
- properties:
entityType:
enum:
- dna_sequence
type: string
type: object
type: object
ContainerQuantity:
description: Quantity of a container, well, or transfer. Supports mass, volume, and other quantities.
properties:
units:
enum:
- L
- mL
- uL
- nL
- pL
- gal (US)
- qt (US)
- pt (US)
- kg
- g
- mg
- ug
- ng
- pg
- lb
- oz
- mol
- mmol
- umol
- nmol
- pmol
- cells
- (x10^3) cells
- (x10^4) cells
- (x10^5) cells
- (x10^6) cells
- (x10^7) cells
- (x10^8) cells
- (x10^9) cells
- items
- units
- null
example: mL
nullable: true
type: string
value:
example: 10
nullable: true
type: number
type: object
AaSequenceWithEntityType:
allOf:
- $ref: '#/components/schemas/AaSequence'
- properties:
entityType:
enum:
- aa_sequence
type: string
type: object
type: object
Fields:
additionalProperties:
$ref: '#/components/schemas/Field'
type: object
RnaSequencePart:
allOf:
- $ref: '#/components/schemas/NucleotideSequencePart'
- properties:
strand:
example: 1
maximum: 1
minimum: 1
type: integer
type: object
DeprecatedContainerVolumeForResponse:
allOf:
- $ref: '#/components/schemas/ContainerQuantity'
- description: 'The deprecated "volume" type key in API responses can also contain non-volume quantities for back-compatibility purposes. Use the "quantity" type key instead.
'
CustomEntityWithEntityType:
allOf:
- $ref: '#/components/schemas/CustomEntity'
- properties:
entityType:
enum:
- custom_entity
type: string
type: object
type: object
Measurement:
properties:
units:
description: Can only be null if value is also null
nullable: true
type: string
value:
description: Can only be null if units is also null
nullable: true
type: number
required:
- value
- units
type: object
CustomField:
properties:
value:
type: string
type: object
NucleotideSequencePart:
properties:
end:
description: 0-based exclusive end index. The end of the sequence is always represented as 0.
type: integer
sequenceId:
example: seq_VfVOART1
type: string
start:
description: 0-based inclusive start index.
type: integer
type: object
DnaOligoWithEntityType:
allOf:
- $ref: '#/components/schemas/DnaOligo'
- properties:
entityType:
enum:
- dna_oligo
type: string
type: object
type: object
BadRequestError:
properties:
error:
allOf:
- $ref: '#/components/schemas/BaseError'
- properties:
type:
enum:
- invalid_request_error
type: string
type: object
EntityOrInaccessibleResource:
oneOf:
- $ref: '#/components/schemas/Entity'
- $ref: '#/components/schemas/InaccessibleResource'
type: object
SequenceFeatureCustomField:
description: A name and value pair associated with a sequence feature (annotation or translation). For genbank imports, these are the qualifiers associated with each feature.
properties:
name:
description: Name of the custom field
type: string
value:
description: Value of the custom field
type: string
type: object
Entity:
discriminator:
mapping:
aa_sequence: '#/components/schemas/AaSequenceWithEntityType'
custom_entity: '#/components/schemas/CustomEntityWithEntityType'
dna_oligo: '#/components/schemas/DnaOligoWithEntityType'
dna_sequence: '#/components/schemas/DnaSequenceWithEntityType'
mixture: '#/components/schemas/MixtureWithEntityType'
molecule: '#/components/schemas/MoleculeWithEntityType'
rna_oligo: '#/components/schemas/RnaOligoWithEntityType'
rna_sequence: '#/components/schemas/RnaSequenceWithEntityType'
propertyName: entityType
oneOf:
- $ref: '#/components/schemas/DnaSequenceWithEntityType'
- $ref: '#/components/schemas/RnaSequenceWithEntityType'
- $ref: '#/components/schemas/AaSequenceWithEntityType'
- $ref: '#/components/schemas/MixtureWithEntityType'
- $ref: '#/components/schemas/DnaOligoWithEntityType'
- $ref: '#/components/schemas/RnaOligoWithEntityType'
- $ref: '#/components/schemas/MoleculeWithEntityType'
- $ref: '#/components/schemas/CustomEntityWithEntityType'
type: object
AaAnnotation:
properties:
color:
type: string
end:
description: 0-based exclusive end index. The end of the AA sequence is always represented as 0.
type: integer
id:
example: prtnann_o7zMPG0P
type: string
name:
maxLength: 255
type: string
notes:
example: Cong et al Science. 2013 Jan 3.
maxLength: 10000
type: string
start:
description: 0-based inclusive start index.
type: integer
type:
example: Site
maxLength: 255
type: string
type: object
DnaAnnotation:
allOf:
- $ref: '#/components/schemas/SequenceFeatureBase'
- properties:
end:
description: 0-based exclusive end index. The end of the sequence is always r
# --- truncated at 32 KB (71 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-plates-api-openapi.yml