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 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