> This page is for Developer Documentation.

> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.benchling.com/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.benchling.com/_mcp/server.

# Batch update MatrixPlateSchema

PATCH https://{tenant_name}.benchling.com/api/v3/matrix-plate-schema:batch-update
Content-Type: application/json

Batch update MatrixPlateSchema synchronously in one transaction. Maximum 25 items per request.

Reference: https://docs.benchling.com/docs/api/benchling-api/matrix-plate-schema/batchupdate

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Headers

- `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3.

### Body (application/json)

This endpoint expects an object.

- `items` (list of UpdateMatrixPlateSchemaInputWithPathParams, required)

## Response

### 200

OK

- `items` (list of MatrixPlateSchema, required)

## Errors

### 400 Matrix Plate Schema Batch Update Request Bad Request Error

Bad Request

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 403 Matrix Plate Schema Batch Update Request Forbidden Error

Forbidden

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 404 Matrix Plate Schema Batch Update Request Not Found Error

Not Found

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 409 Matrix Plate Schema Batch Update Request Conflict Error

Conflict

- `detail` (GeneralErrorDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 429 Matrix Plate Schema Batch Update Request Too Many Requests Error

Too Many Requests

- `detail` (TooManyRequestsErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `invalidId` (string, optional)

### 500 Matrix Plate Schema Batch Update Request Internal Server Error

Internal Server Error

- `detail` (InternalServerErrorBodyDetail, required, nullable)
- `instance` (string, required)
- `status` (integer, required)
- `title` (string, required, nullable)
- `type` (string, required)
- `errorId` (string, optional)

## Types

### UpdateMatrixPlateSchemaInputWithPathParams

- `id` (string, required) — The API ID of the schema to update. The schema must exist and be accessible.
- `archiveReason` (string, optional) — Why the schema was archived.
- `archived` (boolean, optional) — Whether the schema is archived.
- `containerSchemaId` (string, optional, nullable) — The API ID of the container schema constraining what types of containers can be inserted into plates of this type.
- `description` (string, optional) — Updated description. When provided, must be at most 1000 characters.
- `height` (integer, optional) — The number of rows in the grid layout.
- `name` (string, optional) — Updated user-facing name. When provided, must be non-empty after stripping whitespace, at most 255 characters, and unique within the organization.
- `prefix` (string, optional) — 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, optional) — 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.
- `width` (integer, optional) — The number of columns in the grid layout.
- `displayName` (string, optional, deprecated) — Deprecated. Use name instead.

### MatrixPlateSchema

Defines the structure and constraints for a category of MatrixPlates in Benchling's inventory system. A MatrixPlateSchema specifies the grid dimensions (height and width), an optional ContainerSchema for tubes that can be inserted, and custom field definitions. Unlike WellPlateSchema where wells are permanently fixed, MatrixPlateSchema defines plates where containers can be inserted into and removed from positions. Examples include tube racks and sample storage matrices. Each schema is associated with a Registry and given a prefix for generating display IDs.

- `__typename` (string, optional)
- `archiveReason` (string, optional, nullable) — Why the schema was archived.
- `archived` (boolean, optional) — Whether the schema is archived.
- `containerSchema` (ContainerSchemaRef, optional, nullable) — The container schema used for positions in plates of this schema.
- `createdAt` (string, optional) — When the schema was created.
- `description` (string, optional) — A description of the schema.
- `fieldDefinitions` (string, optional) — The fields inherited by plates of this schema.
- `height` (integer, optional) — The number of rows in plates of this schema.
- `id` (string, optional) — The ID of the schema.
- `modifiedAt` (string, optional) — When the schema was last modified.
- `name` (string, optional) — The name of the schema.
- `prefix` (string, optional) — The prefix of barcodes autogenerated for plates of this schema.
- `registry` (RegistryRef, optional) — The schema's registry.
- `systemName` (string, optional) — A unique, stable identifier for this schema used for programmatic access and integrations.
- `width` (integer, optional) — The number of columns in plates of this schema.

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### ContainerSchemaRef

- `__typename` (string, optional)
- `id` (string, optional)

### RegistryRef

- `__typename` (string, optional)
- `id` (string, optional)

## Examples

**Request**

```json
{
  "items": [
    {
      "id": "id"
    }
  ]
}
```

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "archiveReason": "archiveReason",
      "archived": true,
      "createdAt": "createdAt",
      "description": "description",
      "fieldDefinitions": "fieldDefinitions",
      "height": 1,
      "id": "id",
      "modifiedAt": "modifiedAt",
      "name": "name",
      "prefix": "prefix",
      "systemName": "systemName",
      "width": 1
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/matrix-plate-schema:batch-update"

payload = { "items": [{ "id": "id" }] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/matrix-plate-schema:batch-update';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"items":[{"id":"id"}]}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```