---
title: "Update BoxSchema"
method: PATCH
path: "/api/v3/box-schema/{box_schema_id}"
tags: ["Box Schema"]
---

# Update BoxSchema

`PATCH /api/v3/box-schema/{box_schema_id}`

## Request

- Base URL: `https://{tenant_name}.benchling.com`
- URL: `https://{tenant_name}.benchling.com/api/v3/box-schema/{box_schema_id}`
- Auth: HTTP bearer

Update BoxSchema.

## Path parameters

- `box_schema_id` string, required

## Headers

- `EARLY-ACCESS` string

## Request body

- UpdateBoxSchemaInput
  - `archiveReason` string: Why it is being archived. Required when `archived` is `true`, and not allowed when unarchiving.
  - `archived` boolean: Set to `true` to archive or `false` to unarchive it. Archiving requires `archiveReason`.
  - `containerSchemaId` string, nullable: The API ID of the container schema constraining what types of containers can be stored in boxes of this type.
  - `description` string: Updated description. When provided, must be at most 1000 characters.
  - `displayName` string: Deprecated. Use name instead.
  - `height` integer: The number of rows in the grid layout.
  - `name` string: Updated user-facing name. When provided, must be non-empty after stripping whitespace, at most 255 characters, and unique within the organization.
  - `prefix` string: 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: Updated SQL identifier for the warehouse table name. When provided, 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. Changing it requires warehouse table-name changes to be enabled for the caller; otherwise the update fails with a validation error. Supplying the schema's exact current system name always succeeds.
  - `width` integer: The number of columns in the grid layout.

## Response `200`

OK

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