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

# Append worklist item

POST https://{tenant_name}.benchling.com/api/v2-beta/worklists/{worklist_id}/items
Content-Type: application/json

Appends an item to the end of a worklist if the item is not already present in the worklist. Returns 200 OK if the item was already present in the worklist and does not change that item's position.


Reference: https://docs.benchling.com/docs/api/v2-beta/benchling-api-beta/worklists/create-worklist-item

## Authentication

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

## Request

### Path parameters

- `worklist_id` (string, required) — ID of the worklist

### Body (application/json)

This endpoint expects a WorklistItemCreate.

- `itemId` (string, required) — The ID of the item to add to the worklist.

## Response

### 200

OK

- `WorklistItem`

### 201

Created

- `WorklistItem`

## Errors

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

## Types

### Batch

- `archiveRecord` (ArchiveRecord, optional, nullable)
- `createdAt` (datetime, optional) — DateTime at which the the result was created
- `creator` (UserSummary, optional)
- `defaultConcentration` (Measurement, optional)
- `entity` (BatchEntity, optional)
- `fields` (map from string to Field, optional)
- `id` (string, optional)
- `modifiedAt` (datetime, optional)
- `name` (string, optional)
- `schema` (SchemaSummary, optional, nullable)
- `webURL` (string, optional)

### Container

- `archiveRecord` (ArchiveRecord, optional, nullable)
- `barcode` (string, optional, nullable)
- `checkoutRecord` (CheckoutRecord, optional) — *assignee field* is set if status is "RESERVED" or "CHECKED_OUT", or null if status is "AVAILABLE". *comment field* is set when container was last reserved, checked out, or checked into. *modifiedAt field* is the date and time when container was last checked out, checked in, or reserved
- `contents` (list of ContainerContent, optional)
- `createdAt` (datetime, optional)
- `creator` (UserSummary, optional)
- `fields` (map from string to Field, optional)
- `id` (string, optional)
- `modifiedAt` (datetime, optional)
- `name` (string, optional)
- `parentStorageId` (string, optional, nullable)
- `parentStorageSchema` (SchemaSummary, optional, nullable)
- `projectId` (string, optional, nullable)
- `quantity` (ContainerQuantity, optional) — Quantity of a container, well, or transfer. Supports mass, volume, and other quantities.
- `restrictedSampleParties` (list of ContainerRestrictedSamplePartiesItems, optional)
- `restrictionStatus` (enum, optional)
  - Allowed values: `RESTRICTED`, `UNRESTRICTED`, `NOT_APPLICABLE`
- `role` (ExperimentalWellRole, optional, nullable)
- `sampleOwners` (list of ContainerSampleOwnersItems, optional)
- `schema` (SchemaSummary, optional, nullable)
- `volume` (DeprecatedContainerVolumeForResponse, optional) — The deprecated "volume" type key in API responses can also contain non-volume quantities for back-compatibility purposes. Use the "quantity" type key instead.
- `webURL` (string, optional)

### GenericEntity

- `aliases` (list of string, optional)
- `apiURL` (string, optional)
- `archiveRecord` (ArchiveRecord, optional, nullable)
- `authors` (list of UserSummary, optional) — Array of UserSummary Resources of the authors of the entity. This defaults to the creator but can be manually changed.
- `createdAt` (datetime, optional)
- `creator` (GenericEntityCreator, optional) — UserSummary of the user who created the Legacy Request
- `customFields` (map from string to CustomField, optional)
- `entityRegistryId` (string, optional, nullable)
- `fields` (map from string to Field, optional)
- `folderId` (string, optional)
- `id` (string, optional)
- `modifiedAt` (datetime, optional)
- `name` (string, optional)
- `registrationOrigin` (RegistrationOrigin, optional, nullable)
- `registryId` (string, optional, nullable)
- `schema` (SchemaSummary, optional, nullable)
- `webURL` (string, optional)

### Plate

- `archiveRecord` (ArchiveRecord, optional, nullable)
- `availableCapacity` (integer, optional, nullable) — The number of available positions in a matrix plate. Null for well plates.
- `barcode` (string, optional, nullable) — Barcode of the plate
- `createdAt` (datetime, optional) — DateTime the container was created
- `creator` (UserSummary, optional)
- `fields` (map from string to Field, optional)
- `id` (string, optional) — ID of the plate
- `modifiedAt` (datetime, optional) — DateTime the plate was last modified
- `name` (string, optional) — Name of the plate, defaults to barcode if name is not provided.
- `occupiedCapacity` (integer, optional, nullable) — The number of containers currently in a matrix plate. Null for well plates.
- `parentStorageId` (string, optional, nullable) — ID of containing parent inventory (e.g. loc_k2lNspzS).
- `projectId` (string, optional, nullable) — ID of the project if set
- `schema` (SchemaSummary, optional, nullable)
- `totalCapacity` (integer, optional, nullable) — The total capacity of a matrix plate (i.e. how many containers it can store). Null for well plates.
- `type` (enum, optional)
  - Allowed values: `matrix_plate`, `well_plate`
- `webURL` (string, optional)
- `wells` (map from string to WellOrInaccessibleResource, optional) — Well contents of the plate, keyed by position string (eg. "A1").

### BadRequestErrorError

- `message` (string, optional)
- `type` (enum, optional)
  - Allowed values: `invalid_request_error`
- `userMessage` (string, optional)

### ArchiveRecord

- `reason` (string, optional)

### UserSummary

- `handle` (string, optional)
- `id` (string, optional)
- `name` (string, optional)

### Measurement

- `units` (string, required, nullable) — Can only be null if value is also null
- `value` (double, required, nullable) — Can only be null if units is also null

### BatchEntity

- `entityType`: `aa_sequence` (aa_sequence)
  - `id` (string, optional)
  - `type` (string, optional, deprecated)
- `entityType`: `custom_entity` (custom_entity)
  - `id` (string, optional)
  - `type` (string, optional, deprecated)
- `entityType`: `dna_sequence` (dna_sequence)
  - `id` (string, optional)
  - `type` (string, optional, deprecated)

### Field

- `value` (FieldValue, required, nullable) — For single link fields, use the id of the item you want to link (eg. "seq_jdf8BV24"). For multi-link fields, use an array of ids of the items you want to link (eg. ["seq_jdf8BV24"])
- `displayValue` (string, optional, nullable)
- `isMulti` (boolean, optional)
- `textValue` (string, optional, nullable)
- `type` (enum, optional)
  - Allowed values: `dna_sequence_link`, `aa_sequence_link`, `custom_entity_link`, `entity_link`, `mixture_link`, `molecule_link`, `dropdown`, `part_link`, `translation_link`, `aa_part_link`, `base_molecule_link`, `blob_link`, `text`, `long_text`, `batch_link`, `storage_link`, `entry_link`, `assay_request_link`, `assay_result_link`, `assay_run_link`, `boolean`, `float`, `integer`, `datetime`, `date`, `json`

### SchemaSummary

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

### CheckoutRecord

*assignee field* is set if status is "RESERVED" or "CHECKED_OUT", or null if status is "AVAILABLE". *comment field* is set when container was last reserved, checked out, or checked into. *modifiedAt field* is the date and time when container was last checked out, checked in, or reserved

- `assignee` (CheckoutRecordAssignee, optional, nullable)
- `comment` (string, optional)
- `modifiedAt` (datetime, optional)
- `status` (enum, optional)
  - Allowed values: `AVAILABLE`, `RESERVED`, `CHECKED_OUT`

### ContainerContent

- `batch` (BatchOrInaccessibleResource, optional, nullable)
- `concentration` (Measurement, optional)
- `entity` (EntityOrInaccessibleResource, optional, nullable)

### ContainerQuantity

Quantity of a container, well, or transfer. Supports mass, volume, and other quantities.

- `units` (enum, optional, nullable)
  - Allowed values: `L`, `mL`, `uL`, `nL`, `pL`, `gal (US)`, `qt (US)`, `pt (US)`, `kg`, `g`, `mg`, `ug`, `ng`, `pg`, `lb`, `oz`, `mol`, `mmol`, `umol`, `nmol`, `pmol`, `cells`, `(x10^3) cells`, `(x10^4) cells`, `(x10^5) cells`, `(x10^6) cells`, `(x10^7) cells`, `(x10^8) cells`, `(x10^9) cells`, `items`, `units`
- `value` (double, optional, nullable)

### ContainerRestrictedSamplePartiesItems

### ExperimentalWellRole

- `group` (integer, optional)
- `primaryRole` (enum, optional)
  - Allowed values: `SAMPLE`, `CONTROL`, `STANDARD`, `BLANK`
- `subrole` (string, optional, nullable)

### ContainerSampleOwnersItems

### DeprecatedContainerVolumeForResponse

The deprecated "volume" type key in API responses can also contain non-volume quantities for back-compatibility purposes. Use the "quantity" type key instead.

- `units` (enum, optional, nullable)
  - Allowed values: `L`, `mL`, `uL`, `nL`, `pL`, `gal (US)`, `qt (US)`, `pt (US)`, `kg`, `g`, `mg`, `ug`, `ng`, `pg`, `lb`, `oz`, `mol`, `mmol`, `umol`, `nmol`, `pmol`, `cells`, `(x10^3) cells`, `(x10^4) cells`, `(x10^5) cells`, `(x10^6) cells`, `(x10^7) cells`, `(x10^8) cells`, `(x10^9) cells`, `items`, `units`
- `value` (double, optional, nullable)

### GenericEntityCreator

UserSummary of the user who created the Legacy Request

- `handle` (string, optional)
- `id` (string, optional)
- `name` (string, optional)

### CustomField

- `value` (string, optional)

### RegistrationOrigin

- `originEntryId` (string, optional, nullable)
- `registeredAt` (datetime, optional)

### WellOrInaccessibleResource

- `resourceType`: `container` (container)
  - `archiveRecord` (ArchiveRecord, optional, nullable)
  - `barcode` (string, optional) — Barcode of the well
  - `checkoutRecord` (CheckoutRecord, optional) — *assignee field* is set if status is "RESERVED" or "CHECKED_OUT", or null if status is "AVAILABLE". *comment field* is set when container was last reserved, checked out, or checked into. *modifiedAt field* is the date and time when container was last checked out, checked in, or reserved
  - `contents` (list of ContainerContent, optional) — Array of well contents, each with an entity and concentration
  - `createdAt` (datetime, optional) — DateTime the well was created
  - `creator` (UserSummary, optional)
  - `fields` (map from string to Field, optional)
  - `id` (string, optional) — ID of the well
  - `modifiedAt` (datetime, optional) — DateTime the well was last modified
  - `name` (string, optional) — Name of the well, defaults to barcode if name is not provided.
  - `parentStorageId` (string, optional, nullable) — ID of containing parent inventory, a plate well with a coordinate (e.g. plt_2bAks9dx:a2).
  - `parentStorageSchema` (SchemaSummary, optional)
  - `projectId` (string, optional, nullable) — ID of the project if set
  - `quantity` (ContainerQuantity, optional) — Quantity of a container, well, or transfer. Supports mass, volume, and other quantities.
  - `restrictedSampleParties` (list of WellOrInaccessibleResourceDiscriminatorMappingContainerRestrictedSamplePartiesItems, optional) — Not applicable for well plate wells.
  - `restrictionStatus` (enum, optional) — Not applicable for well plate wells.
    - Allowed values: `RESTRICTED`, `UNRESTRICTED`, `NOT_APPLICABLE`
  - `role` (ExperimentalWellRole, optional, nullable) — Not applicable for matrix plate wells.
  - `sampleOwners` (list of WellOrInaccessibleResourceDiscriminatorMappingContainerSampleOwnersItems, optional) — Not applicable for well plate wells.
  - `schema` (SchemaSummary, optional, nullable)
  - `volume` (DeprecatedContainerVolumeForResponse, optional) — The deprecated "volume" type key in API responses can also contain non-volume quantities for back-compatibility purposes. Use the "quantity" type key instead.
  - `webURL` (string, optional)
- `resourceType`: `inaccessible_resource` (inaccessible_resource)
  - `inaccessibleId` (string, optional)
  - `type` (string, optional) — The type of this inaccessible item. Example values: "custom_entity", "container", "plate", "dna_sequence"

### FieldValue

For single link fields, use the id of the item you want to link (eg. "seq_jdf8BV24"). For multi-link fields, use an array of ids of the items you want to link (eg. ["seq_jdf8BV24"])

### CheckoutRecordAssignee

### BatchOrInaccessibleResource

### EntityOrInaccessibleResource

### TeamSummary

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

### WellOrInaccessibleResourceDiscriminatorMappingContainerRestrictedSamplePartiesItems

### WellOrInaccessibleResourceDiscriminatorMappingContainerSampleOwnersItems

### InaccessibleResource

- `inaccessibleId` (string, optional)
- `type` (string, optional) — The type of this inaccessible item. Example values: "custom_entity", "container", "plate", "dna_sequence"

## Examples

### Example 1

**Request**

```json
{
  "itemId": "string"
}
```

**Response**

```json
{
  "archiveRecord": {
    "reason": "Made in error"
  },
  "createdAt": "2024-01-15T09:30:00Z",
  "creator": {
    "handle": "string",
    "id": "string",
    "name": "string"
  },
  "defaultConcentration": {
    "units": "string",
    "value": 1.1
  },
  "entity": {
    "entityType": "dna_sequence",
    "id": "seq_ObbdtGhC",
    "type": "string"
  },
  "fields": {},
  "id": "bat_UOIr8IjL",
  "modifiedAt": "2024-01-15T09:30:00Z",
  "name": "string",
  "schema": {
    "id": "string",
    "name": "string"
  },
  "webURL": "string"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2-beta/worklists/worklist_id/items"

payload = { "itemId": "string" }
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/v2-beta/worklists/worklist_id/items';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"itemId":"string"}'
};

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

### Example 2

**Request**

```json
{
  "itemId": "string"
}
```

**Response**

```json
{
  "archiveRecord": {
    "reason": "Made in error"
  },
  "createdAt": "2024-01-15T09:30:00Z",
  "creator": {
    "handle": "string",
    "id": "string",
    "name": "string"
  },
  "defaultConcentration": {
    "units": "string",
    "value": 1.1
  },
  "entity": {
    "entityType": "dna_sequence",
    "id": "seq_ObbdtGhC",
    "type": "string"
  },
  "fields": {},
  "id": "bat_UOIr8IjL",
  "modifiedAt": "2024-01-15T09:30:00Z",
  "name": "string",
  "schema": {
    "id": "string",
    "name": "string"
  },
  "webURL": "string"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2-beta/worklists/worklist_id/items"

payload = { "itemId": "string" }
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/v2-beta/worklists/worklist_id/items';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"itemId":"string"}'
};

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