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 Location API
version: 2.0.0
description: 'A Location represents a physical storage area in Benchling''s inventory system, such as
a freezer, refrigerator, shelf, room, or building. Locations form a hierarchy where
each location can contain child locations (e.g., a freezer contains shelves) as well
as inventory items like Boxes, Plates, and Containers when allowNonLocationChildren is
true. Each location tracks its capacity (totalCapacity, availableCapacity, occupiedCapacity)
and can restrict what types of items it accepts via allowedInventorySchemas. Locations
conform to a LocationSchema that defines custom fields for the location type. Locations
are identified by barcode for physical tracking and can be archived when no longer in use.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A Location represents a physical storage area in Benchling''s inventory system, such as
a freezer, refrigerator, shelf, room, or building. Locations form a hierarchy where
each location can contain child locations (e.g., a freezer contains shelves) as well
as inventory items like Boxes, Plates, and Containers when allowNonLocationChildren is
true. Each location tracks its capacity (totalCapacity, availableCapacity, occupiedCapacity)
and can restrict what types of items it accepts via allowedInventorySchemas. Locations
conform to a LocationSchema that defines custom fields for the location type. Locations
are identified by barcode for physical tracking and can be archived when no longer in use.'
name: Location
x-bnch-core-type: Location
x-bnch-organization: Benchling
paths:
/location:
post:
description: Create Location.
operationId: Location.Create
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/CreateLocationInput'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
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 Location
tags:
- Location
x-bnch-rate-limit-tier: 4
/location/items:
get:
description: List Location items.
operationId: Location.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/LocationPaginatedList'
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 Location items
tags:
- Location
x-bnch-rate-limit-tier: 4
/location/{location_id}:
get:
description: Get a single Location by ID.
operationId: Location.Get
parameters:
- description: ID of the Location.
in: path
name: location_id
required: true
schema:
type: string
- $ref: '#/components/parameters/returning'
- $ref: '#/components/parameters/omit'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
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 Location by ID
tags:
- Location
x-bnch-rate-limit-tier: 5
patch:
description: Update Location.
operationId: Location.Update
parameters:
- description: ID of the Location.
in: path
name: location_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/UpdateLocationInput'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/Location'
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 Location
tags:
- Location
x-bnch-rate-limit-tier: 4
/location:batch-create:
post:
description: Batch create Location synchronously in one transaction. Maximum 25 items per request.
operationId: Location.BatchCreate
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/CreateLocationInput'
maxItems: 25
minItems: 1
type: array
required:
- items
type: object
responses:
'201':
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Location'
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 Location
tags:
- Location
x-bnch-rate-limit-tier: 3
/location:batch-update:
patch:
description: Batch update Location synchronously in one transaction. Maximum 25 items per request.
operationId: Location.BatchUpdate
requestBody:
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/UpdateLocationInputWithPathParams'
maxItems: 25
minItems: 1
type: array
required:
- items
type: object
responses:
'200':
content:
application/json:
schema:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Location'
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 Location
tags:
- Location
x-bnch-rate-limit-tier: 3
/location:bulk-create:
post:
description: Bulk create Location.
operationId: Location.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 Location
tags:
- Location
x-bnch-rate-limit-tier: 2
/location:bulk-update:
patch:
description: Bulk update Location.
operationId: Location.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 Location
tags:
- Location
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
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
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
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:
LocationPaginatedList:
additionalProperties: false
properties:
items:
items:
$ref: '#/components/schemas/Location'
type: array
nextToken:
type: string
type: object
FieldValueInput:
additionalProperties: false
properties:
value:
$ref: '#/components/schemas/AnyType'
required:
- value
type: object
AnyType: {}
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
UpdateLocationInputWithPathParams:
additionalProperties: false
properties:
archiveReason:
type: string
archived:
type: boolean
barcode:
type: string
id:
type: string
name:
type: string
parentStorageId:
type:
- 'null'
- string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
type: object
required:
- id
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
Location:
allOf:
- $ref: '#/components/schemas/ILocation'
- description: 'A Location represents a physical storage area in Benchling''s inventory system, such as
a freezer, refrigerator, shelf, room, or building. Locations form a hierarchy where
each location can contain child locations (e.g., a freezer contains shelves) as well
as inventory items like Boxes, Plates, and Containers when allowNonLocationChildren is
true. Each location tracks its capacity (totalCapacity, availableCapacity, occupiedCapacity)
and can restrict what types of items it accepts via allowedInventorySchemas. Locations
conform to a LocationSchema that defines custom fields for the location type. Locations
are identified by barcode for physical tracking and can be archived when no longer in use.'
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
ILocation:
properties:
__typename:
type: string
allowNonLocationChildren:
description: Whether this location can store plates, boxes, and containers.
type: boolean
allowedInventorySchemas:
description: 'The plate, box, and container schemas that can be stored in this location.
If allowsNonLocationChildren is true and this list is empty, all schemas are allowed.'
items:
$ref: '#/components/schemas/ObjectRef'
description: Union of BoxSchema, PlateSchema, ContainerSchema
type: array
archiveReason:
type:
- 'null'
- string
archived:
type: boolean
availableCapacity:
description: The number of available positions in this location. Null if totalCapacity is not set.
type:
- 'null'
- integer
barcode:
type:
- 'null'
- string
createdAt:
format: datetime
type:
- 'null'
- string
id:
type: string
modifiedAt:
format: datetime
type:
- 'null'
- string
name:
type:
- 'null'
- string
occupiedCapacity:
description: 'The number of plates, boxes, and containers currently in this location.
Null if totalCapacity is not set.'
type:
- 'null'
- integer
parentStorage:
oneOf:
- $ref: '#/components/schemas/LocationRef'
- type: 'null'
schema:
oneOf:
- $ref: '#/components/schemas/LocationSchemaRef'
- type: 'null'
totalCapacity:
description: 'The total capacity of this location (i.e. how many plates, boxes, and containers it can store).
If null, capacity is not limited.'
type:
- 'null'
- integer
validationStatus:
description: Whether this location is passing all validation checks.
enum:
- PASSED
- FAILED
type: string
type: object
LocationSchemaRef:
properties:
__typename:
type: string
id:
format: api_id
type: string
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
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
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
CreateLocationInput:
additionalProperties: false
properties:
barcode:
type: string
name:
type: string
parentStorageId:
type: string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
type: object
schemaId:
type: string
required:
- name
- schemaId
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
UpdateLocationInput:
additionalProperties: false
properties:
archiveReason:
type: string
archived:
type: boolean
barcode:
type: string
name:
type: string
parentStorageId:
type:
- 'null'
- string
schemaFields:
additionalProperties:
$ref: '#/components/schemas/FieldValueInput'
type: object
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
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
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'
descripti
# --- truncated at 32 KB (33 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-location-api-openapi.yml