openapi: 3.0.1
info:
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: Benchling AA Sequences Containers 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: '
Containers are the backbone of sample management in Benchling. They represent physical containers, such as tubes or wells, that hold quantities of biological samples (represented by the entities inside the container). The container itself tracks its total volume, and the concentration of every entity inside of it.
Containers are all associated with schemas, which define the type of the container (e.g. "Tube") along with the fields that are tracked.
Like all inventory, every container has a barcode that is unique across the registry.
'
name: Containers
paths:
/containers:
get:
description: List containers
operationId: listContainers
parameters:
- description: Number of results to return.
in: query
name: pageSize
schema:
default: 50
maximum: 100
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
enum:
- createdAt
- barcode
- modifiedAt
- name
- barcode:asc
- modifiedAt:asc
- name:asc
- barcode:desc
- modifiedAt:desc
- name:desc
- 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 container. Restricts results to those with the specified name.
in: query
name: name
schema:
type: string
- description: 'Name substring of a container. Restricts results to those with names that include the provided substring.
'
in: query
name: nameIncludes
schema:
type: string
- description: ID of a plate, box, or location. Restricts results to those located in the specified inventory.
in: query
name: ancestorStorageId
schema:
type: string
- description: 'ID of an entity or entity schema. Restricts results to those that contain the specified entities or entities of the specified schema.
'
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 containers. Use "ANY_ARCHIVED" to filter for archived containers 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 check-out statuses. Restricts results to those that match one of the specified statuses. Valid statuses are AVAILABLE, RESERVED, and CHECKED_OUT.
'
in: query
name: checkoutStatus
schema:
enum:
- AVAILABLE
- RESERVED
- CHECKED_OUT
type: string
- description: 'Comma-separated list of user or team IDs. Maximum of 100. Restricts results to those that are reserved or checked out for a user or team who matches any of the specified IDs or returns a 400 error with a list of invalid IDs.
'
in: query
name: checkoutAssigneeIds.anyOf
schema:
example: ent_a0SApq3z,team_Il92ydiY
type: string
- description: 'Comma-separated list of restriction statuses. Restricts results to those that match one of the specified statuses. Valid statuses are RESTRICTED, UNRESTRICTED, and NOT_APPLICABLE.
'
in: query
name: restrictionStatus
schema:
$ref: '#/components/schemas/SampleRestrictionStatus'
- description: 'Comma-separated list of user or team IDs. Restricts results to those that match all of the specified IDs or returns a 400 error with a list of invalid IDs.
'
in: query
name: sampleOwnerIds.allOf
schema:
example: ent_a0SApq3z,team_Il92ydiY
type: string
- description: 'Comma-separated list of user or team IDs. Maximum of 100. Restricts results to those that match any of the specified IDs or returns a 400 error with a list of invalid IDs.
'
in: query
name: sampleOwnerIds.anyOf
schema:
example: ent_a0SApq3z,team_Il92ydiY
type: string
- description: 'Comma-separated list of user or team IDs. Restricts results to those that do not match any of the specified IDs or returns a 400 error with a list of invalid IDs.
'
in: query
name: sampleOwnerIds.noneOf
schema:
example: ent_a0SApq3z,team_Il92ydiY
type: string
- description: 'Comma-separated list of user, team, or app IDs. Restricts results to those that match all of the specified IDs or returns a 400 error with a list of invalid IDs.
'
in: query
name: restrictedSamplePartyIds.allOf
schema:
example: ent_a0SApq3z,team_Il92ydiY
type: string
- description: 'Comma-separated list of user, team, or app IDs. Maximum of 100. Restricts results to those that match any of the specified IDs or returns a 400 error with a list of invalid IDs.
'
in: query
name: restrictedSamplePartyIds.anyOf
schema:
example: ent_a0SApq3z,team_Il92ydiY
type: string
- description: 'Comma-separated list of user, team, or app IDs. Restricts results to those that do not match any of the specified IDs or returns a 400 error with a list of invalid IDs.
'
in: query
name: restrictedSamplePartyIds.noneOf
schema:
example: ent_a0SApq3z,team_Il92ydiY
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: con_Q6uhNZvw,con_OwmERWGE,con_nzuDFhNvz
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: W103371,W103343,W103366
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 users IDs
in: query
name: creatorIds
schema:
example: ent_a0SApq3z
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: containers.id,containers.modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersPaginatedList'
description: OK
'400':
content:
application/json:
schema:
allOf:
- $ref: '#/components/schemas/BadRequestError'
properties:
invalidIds:
items:
type: string
type: array
type: object
description: Bad Request
summary: List containers
tags:
- Containers
post:
description: Create a new container
operationId: createContainer
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerCreate'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Container'
description: Created
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Create a new container
tags:
- Containers
/containers/{container_id}:
get:
description: get a container by id
operationId: getContainer
parameters:
- in: path
name: container_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,modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Container'
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 container by id
tags:
- Containers
patch:
description: update a container
operationId: updateContainer
parameters:
- in: path
name: container_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerUpdate'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Container'
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
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
description: Not Found
summary: update a container
tags:
- Containers
/containers/{container_id}/contents:
get:
description: List a container's contents
operationId: listContainerContents
parameters:
- in: path
name: container_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerContentsList'
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: List a container's contents
tags:
- Containers
/containers/{container_id}/contents/{containable_id}:
delete:
description: Delete a container content
operationId: deleteContainerContent
parameters:
- in: path
name: container_id
required: true
schema:
type: string
- in: path
name: containable_id
required: true
schema:
type: string
responses:
'204':
description: No Content
'403':
content:
application/json:
schema:
$ref: '#/components/schemas/ForbiddenRestrictedSampleError'
description: Forbidden
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
description: Not Found
summary: Delete a container content
tags:
- Containers
get:
description: Get a container content
operationId: getContainerContent
parameters:
- in: path
name: container_id
required: true
schema:
type: string
- in: path
name: containable_id
required: true
schema:
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerContent'
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 container content
tags:
- Containers
patch:
description: Update a container content
operationId: updateContainerContent
parameters:
- in: path
name: container_id
required: true
schema:
type: string
- in: path
name: containable_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerContentUpdate'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerContent'
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
'404':
content:
application/json:
schema:
$ref: '#/components/schemas/NotFoundError'
description: Not Found
summary: Update a container content
tags:
- Containers
/containers/{destination_container_id}:transfer:
post:
description: 'Transfers a volume of an entity or container into a destination container.
Transfering a volume is cumulative with the existing destination container''s contents. To transfer an entire container''s contents, the sourceContainerId should be specified. To otherwise transfer multiple entities within a container, you can make multiple calls to this endpoint, specifying a single entity with each call.
'
operationId: transferIntoContainer
parameters:
- in: path
name: destination_container_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainerTransfer'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyObject'
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: Transfer into container
tags:
- Containers
/containers:archive:
post:
description: Archive containers
operationId: archiveContainers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersArchive'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersArchivalChange'
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 containers
tags:
- Containers
/containers:bulk-create:
post:
description: Bulk create containers
operationId: bulkCreateContainers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersBulkCreateRequest'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
The task response contains the full list of Containers that were created.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Bulk create containers. Limit of 1000 containers per request.
tags:
- Containers
/containers:bulk-get:
get:
description: Bulk get a set of containers. Provide either containerIds or barcodes, not both.
operationId: bulkGetContainers
parameters:
- description: 'Comma-separated list of container IDs.
'
in: query
name: containerIds
schema:
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 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: containers.id,containers.modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersList'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Bulk get a set of containers
tags:
- Containers
/containers:bulk-update:
post:
description: Bulk update containers
operationId: bulkUpdateContainers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersBulkUpdateRequest'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
The task response contains the full list of Containers that were updated.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Bulk update containers
tags:
- Containers
/containers:check-in:
post:
description: Check in containers to signify that they are available for use.
operationId: checkinContainers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersCheckin'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyObject'
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: Check in containers
tags:
- Containers
/containers:check-out:
post:
description: Check out containers to signify that they are in use.
operationId: checkoutContainers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersCheckout'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyObject'
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: Check out containers
tags:
- Containers
/containers:print-labels:
post:
description: Print labels. Supported print methods are "REMOTE_PRINT_SERVER", "LEGACY_HTTP", and "LEGACY_TCP".
operationId: printLabels
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/PrintLabels'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyObject'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Print labels
tags:
- Containers
/containers:reserve:
post:
description: Reserve containers to signify that someone plans to use the containers.
operationId: reserveContainers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersCheckout'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/EmptyObject'
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: Reserve containers
tags:
- Containers
/containers:unarchive:
post:
description: Unarchive containers
operationId: unarchiveContainers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersUnarchive'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/ContainersArchivalChange'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Unarchive containers
tags:
- Containers
/transfers:
post:
description: 'Transfers a volume of an entity or container into a destination container. Limit of 5000 transfers per request. Concentration of all contents in the destination container will be automatically updated based on the previous volume & concentrations of the contents in that container, the concentration of the contents being transferred in, the volume of the contents being transferred in, and the final volume of the container. If no concentration is specified, the concentration will not be tracked.
'
operationId: transferIntoContainers
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MultipleContainersTransfersList'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
The task response contains the full list of destination [containers](#/Containers/getContainer).
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Transfers into containers
tags:
- Containers
components:
schemas:
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
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.
'
ExperimentalWellRole:
properties:
group:
type: integer
primaryRole:
enum:
- SAMPLE
- CONTROL
- STANDARD
- BLANK
type: string
subrole:
nullable: true
type: string
type: object
ContainerBulkUpdateItem:
allOf:
- $ref: '#/components/schemas/ContainerWriteBase'
- properties:
concentration:
allOf:
- $ref: '#/components/schemas/Measurement'
description: 'Concentration for the container. Only valid for single content containers. Null values will be ignored.
'
example:
units: g/mL
value: 10
containerId
# --- truncated at 32 KB (90 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-containers-api-openapi.yml