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' 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 of client credentials OAuth flow prior to receiving a bearer token. scheme: basic type: http oAuth: description: OAuth2 Client Credentials flow intended for service access flows: clientCredentials: scopes: {} tokenUrl: /oauth/token type: oauth2