--- title: "Create BoxSchema" method: POST path: "/api/v3/box-schema" tags: ["Box Schema"] --- # Create BoxSchema `POST /api/v3/box-schema` ## Request - Base URL: `https://{tenant_name}.benchling.com` - URL: `https://{tenant_name}.benchling.com/api/v3/box-schema` - Auth: HTTP bearer Create BoxSchema. ## Headers - `EARLY-ACCESS` string ## Request body - CreateBoxSchemaInput - `containerSchemaId` string: The API ID of the container schema constraining what types of containers can be stored in boxes of this type. - `description` string, required: A human-readable description of the schema. At most 1000 characters. - `displayName` string: Deprecated. Use name instead. - `fieldDefinitions` CreateBoxSchemaInputFieldDefinitionsItems[] - union - CreateBooleanFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'BOOLEAN', required - CreateDateFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DATE', required - CreateDateTimeFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DATE_TIME', required - CreateDecimalFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `displayPrecision` integer: The number of decimal places to display (0 to 10). - `isRequired` boolean, required: When true, a value must be provided for this field. - `legalTextDropdownId` string: The API ID of the legal text dropdown associated with this field definition. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `numericMax` number, double: The maximum allowed value, inclusive. - `numericMin` number, double: The minimum allowed value, inclusive. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DECIMAL', required - `unitId` string: The API ID of the unit to associate with this field. - CreateIntegerFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `numericMax` number, double: The maximum allowed value, inclusive. - `numericMin` number, double: The minimum allowed value, inclusive. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'INTEGER', required - `unitId` string: The API ID of the unit to associate with this field. - CreateLongTextFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'LONG_TEXT', required - CreateTextFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'TEXT', required - CreateAaSequenceLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'AA_SEQUENCE_LINK', required - CreateAttachmentLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'ATTACHMENT_LINK', required - CreateCustomEntityLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'CUSTOM_ENTITY_LINK', required - CreateDnaOligoLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, required: The API ID of the schema/interface that linked items must belong to. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DNA_OLIGO_LINK', required - CreateDnaSequenceLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DNA_SEQUENCE_LINK', required - CreateDropdownLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `dropdownId` string, required: The API ID of the Dropdown that defines the available options. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'DROPDOWN', required - CreateAnyEntityLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'ENTITY_LINK', required - CreateEntryLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isRequired` boolean, required: When true, a value must be provided for this field. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'ENTRY_LINK', required - CreateEquipmentLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'EQUIPMENT_LINK', required - CreateMixtureLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'MIXTURE_LINK', required - CreateMoleculeLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'MOLECULE_LINK', required - CreateOligoConjugateLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'OLIGO_CONJUGATE_LINK', required - CreateOligoDuplexLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'OLIGO_DUPLEX_LINK', required - CreateProteinLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'PROTEIN_LINK', required - CreateRnaSequenceLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, required: The API ID of the schema/interface that linked items must belong to. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'RNA_SEQUENCE_LINK', required - CreateRnaOligoLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isParent` boolean: When true, indicates a parent-child relationship used in the registry's lot-numbering functionality. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, required: The API ID of the schema/interface that linked items must belong to. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'RNA_OLIGO_LINK', required - CreateStorableLinkFieldDefinitionInput - `description` string: An optional user-provided description of this field definition. - `isMulti` boolean, required: When true, multiple linked values are allowed. - `isRequired` boolean, required: When true, a value must be provided for this field. - `linkDefinitionId` string, nullable, required: The API ID of the schema to constrain links to, or null to allow links to any item of the linked type. - `name` string, required: The user-facing display name of this field definition. Must be unique within the schema. - `systemName` string, required: The machine-readable identifier used as the warehouse column name. Must be unique within the schema. - `type` 'STORAGE_LINK', required - `height` integer, required: The number of rows in the grid layout. - `name` string: The user-facing name of the schema. Must be non-empty after stripping whitespace, at most 255 characters, and unique within the organization. - `organizationId` string, required: The API ID of the organization this schema belongs to. The organization must exist and be accessible to the caller. - `prefix` string, required: The prefix used for auto-generating barcodes for inventory items of this schema. Must be unique within the registry and cannot end in a digit. - `systemName` string: The SQL identifier used as the warehouse table name. If not provided, one is auto-generated from the display name. Must match the pattern [a-z_][a-z0-9_$]*, cannot be a reserved table name, cannot start with 'bnch$', and must be unique within the organization. - `width` integer, required: The number of columns in the grid layout. ## Response `201` Created - BoxSchema: Defines the structure and constraints for a category of Boxes in Benchling's inventory system. A BoxSchema specifies the grid dimensions (height and width) determining how many container positions the box has, and optionally links to a ContainerSchema that constrains what type of containers can be stored in boxes of this type. BoxSchemas support custom field definitions for capturing additional metadata about boxes. Each BoxSchema can be associated with a Registry and given a prefix for generating display IDs. Examples include "96-Well Freezer Box" or "81-Position Cryo Box". - `__typename` string - `archiveReason` string, nullable - `archived` boolean - `containerSchema` ContainerSchemaRef - `__typename` string - `id` string, api_id - `createdAt` string, datetime, nullable - `description` string: A description of the schema. - `fieldDefinitions` string, uri - `height` integer, nullable - `id` string - `modifiedAt` string, datetime, nullable - `name` string - `prefix` string, nullable - `registry` RegistryRef - `__typename` string - `id` string, api_id - `systemName` string: A unique, stable identifier for this schema used for programmatic access and integrations. - `type` string, nullable - `width` integer, nullable ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `429`: Too Many Requests - `500`: Internal Server Error --- [API](https://skmtc.dev/benchling/apis/benchling-api.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api/revisions/c9f087b98b8b?raw)