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 Box API
version: 2.0.0
description: 'A Box is a grid-based storage container in Benchling''s inventory system, designed
to hold multiple sample containers (tubes, vials, etc.) in an organized layout.
Boxes have a defined capacity based on their schema''s height and width dimensions,
and track how many positions are occupied, empty, or available. Each box is
assigned a barcode for physical tracking and must be placed within a Location (via
parentStorage). Boxes conform to a BoxSchema that defines their grid dimensions and
which ContainerSchema their contents must use. Boxes are commonly used to organize
samples in freezers, refrigerators, or other storage equipment.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A Box is a grid-based storage container in Benchling''s inventory system, designed
to hold multiple sample containers (tubes, vials, etc.) in an organized layout.
Boxes have a defined capacity based on their schema''s height and width dimensions,
and track how many positions are occupied, empty, or available. Each box is
assigned a barcode for physical tracking and must be placed within a Location (via
parentStorage). Boxes conform to a BoxSchema that defines their grid dimensions and
which ContainerSchema their contents must use. Boxes are commonly used to organize
samples in freezers, refrigerators, or other storage equipment.'
name: Box
x-bnch-core-type: Box
x-bnch-organization: Benchling
paths:
/box:
post:
description: Create Box.
operationId: Box.Create
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateBoxInput'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Box'
description: Created
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Create Box
tags:
- Box
x-bnch-rate-limit-tier: 4
/box/items:
get:
description: List Box items.
operationId: Box.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
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/BoxPaginatedList'
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 Box items
tags:
- Box
x-bnch-rate-limit-tier: 4
/box/{box_id}:
get:
description: Get a single Box by ID.
operationId: Box.Get
parameters:
- description: ID of the Box.
in: path
name: box_id
required: true
schema:
type: string
- $ref: '#/components/parameters/returning'
- $ref: '#/components/parameters/omit'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Box'
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 Box by ID
tags:
- Box
x-bnch-rate-limit-tier: 5
patch:
description: Update Box.
operationId: Box.Update
parameters:
- description: ID of the Box.
in: path
name: box_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateBoxInput'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Box'
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Update Box
tags:
- Box
x-bnch-rate-limit-tier: 4
/box:batch-create:
post:
description: Batch create Box synchronously in one transaction. Maximum 25 items per request.
operationId: Box.BatchCreate
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/CreateBoxInput'
maxItems: 25
minItems: 1
type: array
required:
- items
type: object
responses:
'201':
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Box'
type: array
required:
- items
type: object
description: Created
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Batch create Box
tags:
- Box
x-bnch-rate-limit-tier: 3
/box:batch-update:
patch:
description: Batch update Box synchronously in one transaction. Maximum 25 items per request.
operationId: Box.BatchUpdate
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/UpdateBoxInputWithPathParams'
maxItems: 25
minItems: 1
type: array
required:
- items
type: object
responses:
'200':
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Box'
type: array
required:
- items
type: object
description: OK
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Batch update Box
tags:
- Box
x-bnch-rate-limit-tier: 3
/box:bulk-create:
post:
description: Bulk create Box.
operationId: Box.BulkCreate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkImport'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: Task started
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Bulk create Box
tags:
- Box
x-bnch-rate-limit-tier: 2
/box:bulk-update:
patch:
description: Bulk update Box.
operationId: Box.BulkUpdate
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/BulkImport'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: Task started
'400':
$ref: '#/components/responses/BadRequest'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
'500':
$ref: '#/components/responses/InternalServerError'
summary: Bulk update Box
tags:
- Box
x-bnch-rate-limit-tier: 2
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
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
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
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
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
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
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.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:
FieldValueInput:
additionalProperties: false
properties:
value:
$ref: '#/components/schemas/AnyType'
required:
- value
type: object
AnyType: {}
UpdateBoxInput:
additionalProperties: false
properties:
archiveReason:
type: string
archived:
type: boolean
barcode:
type: string
name:
type: string
parentStorageId:
type:
- 'null'
- string
projectId:
type:
- 'null'
- string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
type: object
type: object
DateValue:
description: A type that represents date values.
properties:
__typename:
type: string
value:
description: The date value.
format: date
type: string
type: object
BooleanValue:
description: A type that represents boolean values.
properties:
__typename:
type: string
value:
description: The boolean value.
type: boolean
type: object
ProjectRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
ObjectLinkValue:
description: A type that represents links to other objects.
properties:
__typename:
type: string
value:
$ref: '#/components/schemas/ObjectRef'
description: The object that this value links to, or an Inaccessible object if not found with the current permission set.
type: object
BoxPaginatedList:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Box'
type: array
nextToken:
type: string
type: object
Box:
allOf:
- $ref: '#/components/schemas/IBox'
- description: 'A Box is a grid-based storage container in Benchling''s inventory system, designed
to hold multiple sample containers (tubes, vials, etc.) in an organized layout.
Boxes have a defined capacity based on their schema''s height and width dimensions,
and track how many positions are occupied, empty, or available. Each box is
assigned a barcode for physical tracking and must be placed within a Location (via
parentStorage). Boxes conform to a BoxSchema that defines their grid dimensions and
which ContainerSchema their contents must use. Boxes are commonly used to organize
samples in freezers, refrigerators, or other storage equipment.'
properties:
__typename:
type: string
creator:
oneOf:
- $ref: '#/components/schemas/PrincipalRef'
- type: 'null'
schemaFields:
oneOf:
- items:
$ref: '#/components/schemas/SchemaFieldValue'
type: array
- 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
AsyncTaskLink:
properties:
pollingUri:
format: uri
type: string
taskId:
type: string
type: object
ArrayValue:
description: A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns).
properties:
__typename:
type: string
value:
items:
anyOf:
- $ref: '#/components/schemas/BooleanValue'
- $ref: '#/components/schemas/DateTimeValue'
- $ref: '#/components/schemas/DateValue'
- $ref: '#/components/schemas/DecimalValue'
- $ref: '#/components/schemas/IntegerValue'
- $ref: '#/components/schemas/JsonValue'
- $ref: '#/components/schemas/ObjectLinkValue'
- $ref: '#/components/schemas/ObjectLinkListValue'
- $ref: '#/components/schemas/TextAndUrlValue'
- $ref: '#/components/schemas/TextValue'
description: Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue
discriminator:
propertyName: __typename
type: array
type: object
LocationRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
BulkImport:
example:
fileId: scrfile_jdf8BV24kLmN
properties:
fileId:
description: The API ID of the scratch file (`scrfile_XXXXXXXX`) containing the items to import. The referenced file must be a scratch file whose upload has completed successfully.
type: string
required:
- fileId
type: object
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
ObjectRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
BoxSchemaRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
type: object
UpdateBoxInputWithPathParams:
additionalProperties: false
properties:
archiveReason:
type: string
archived:
type: boolean
barcode:
type: string
id:
type: string
name:
type: string
parentStorageId:
type:
- 'null'
- string
projectId:
type:
- 'null'
- string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
type: object
required:
- id
type: object
CreateBoxInput:
additionalProperties: false
properties:
barcode:
type: string
name:
type: string
parentStorageId:
type: string
projectId:
type: string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
type: object
schemaId:
type: string
required:
- schemaId
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
IBox:
properties:
__typename:
type: string
archiveReason:
type:
- 'null'
- string
archived:
type: boolean
availableCapacity:
description: The number of available positions in the box.
type: integer
barcode:
type:
- 'null'
- string
createdAt:
format: datetime
type:
- 'null'
- string
emptyContainers:
description: The number of containers in the box that have no contents.
type:
- 'null'
- integer
id:
type: string
modifiedAt:
format: datetime
type:
- 'null'
- string
name:
type:
- 'null'
- string
occupiedCapacity:
description: The number of containers currently in the box.
type: integer
parentStorage:
oneOf:
- $ref: '#/components/schemas/LocationRef'
- type: 'null'
project:
oneOf:
- $ref: '#/components/schemas/ProjectRef'
- type: 'null'
schema:
oneOf:
- $ref: '#/components/schemas/BoxSchemaRef'
- type: 'null'
totalCapacity:
description: The total capacity of the box (i.e. how many containers it can store).
type: integer
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
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
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
responses:
NotFound:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/GeneralError'
description: Not Found
TooManyRequests:
content:
application/problem+json:
schema:
$ref: '#/components/schemas/GeneralError'
description: Too Many Requests
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
# --- truncated at 32 KB (32 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-box-api-openapi.yml