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

POST https://{tenant_name}.benchling.com/api/v3/worklist:batch-create
Content-Type: application/json

Batch create Worklist synchronously in one transaction. Maximum 25 items per request.

Reference: https://docs.benchling.com/docs/api/benchling-api/worklist/batchcreate

## 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 CreateWorklistInput, required)

## Response

### 201

Created

- `items` (list of Worklist, required)

## Errors

### 400 Worklist Batch Create 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 Worklist Batch Create 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 Worklist Batch Create 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 Worklist Batch Create 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 Worklist Batch Create 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)
- `violated-policies` (list of enum, optional) — The budget policies that rejected the request, in canonical order: `user`, `integration`, then `tenant`.
  - Allowed values: `user`, `integration`, `tenant`

### 500 Worklist Batch Create 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

### CreateWorklistInput

- `itemType` (enum, required)
  - Allowed values: `CONTAINER`, `ENTITY`, `PLATE`
- `name` (string, required)
- `itemIds` (list of string, optional)

### Worklist

A typed collection of items used to group related objects for batch operations. Unlike folders, items can belong to multiple worklists simultaneously, making worklists useful as temporary holding grounds for arbitrary groups of items. Each worklist has an `itemType` that restricts what kinds of objects it can contain (containers, entities, or plates). Common use cases include scanning containers into a worklist before adding them to a transfer table, or grouping entities for bulk export. Worklists have an `owner` and support `collaborations` for access control (see `Collaboratable` interface). The `items` field returns the collection of `Worklistable` objects currently in the worklist.

- `__typename` (string, optional)
- `createdAt` (string, optional, nullable)
- `creator` (PrincipalRef, optional, nullable)
- `id` (string, optional)
- `itemType` (enum, optional)
  - Allowed values: `CONTAINER`, `ENTITY`, `PLATE`
- `items` (string, optional)
- `modifiedAt` (string, optional, nullable)
- `name` (string, optional, nullable)
- `owner` (OwnerRef, optional)

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### PrincipalRef

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

### OwnerRef

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

## Examples

**Request**

```json
{
  "items": [
    {
      "itemType": "CONTAINER",
      "name": "name"
    }
  ]
}
```

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "createdAt": "createdAt",
      "id": "id",
      "itemType": "CONTAINER",
      "items": "items",
      "modifiedAt": "modifiedAt",
      "name": "name"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/worklist:batch-create"

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

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

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/worklist:batch-create';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"items":[{"itemType":"CONTAINER","name":"name"}]}'
};

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