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

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

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

Reference: https://docs.benchling.com/docs/api/benchling-api/feature-library-item/batchcreate

## Authentication

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

## Request

### Body (application/json)

This endpoint expects an object.

- `items` (list of CreateFeatureLibraryItemInput, required)

## Response

### 201

Created

- `items` (list of FeatureLibraryItem, required)

## Errors

### 400 Feature Library Item 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 Feature Library Item 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 Feature Library Item 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 Feature Library Item 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 Feature Library Item 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 Feature Library Item 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

### CreateFeatureLibraryItemInput

- `color` (string, required) — Must be a valid hex color string (for example, `#F58A5E`).
- `featureLibraryId` (string, required) — Feature library id to contain this feature. Each library supports at most 5,000 items.
- `matchType` (enum, required) — Determines how `pattern` is interpreted during auto-annotation (`NUCLEOTIDE` or `AA_SEQUENCE`). Required on create and cannot be changed on update.
  - Allowed values: `NUCLEOTIDE`, `AA_SEQUENCE`
- `name` (string, required) — Item names must be non-empty after trimming whitespace and at most 255 characters.
- `pattern` (string, required) — Patterns must be non-empty and valid for the item's `matchType`. Nucleotide patterns accept IUPAC bases plus wildcards (`#`, `<`, `>`, `()`). Amino acid patterns accept standard residues plus the same wildcard characters. Patterns are compared case-insensitively within a library, so two items cannot differ only by letter case.
- `featureType` (string, optional) — The type of the Feature Library Item, like gene, promoter, etc. Note: This is an arbitrary string, not an enum

### FeatureLibraryItem

Represents a single feature definition within a FeatureLibrary used for auto-annotation. Each item defines a searchable pattern (nucleotide or amino acid sequence), a feature type classification (such as 'gene', 'promoter', or 'domain'), a display name, and a color for visualization. When auto-annotate runs against a sequence, the pattern is matched according to the matchType (see FeatureLibraryMatchType), and matching regions are annotated with the item's name, type, and color. Patterns can include special characters for flexible matching, such as wildcards for arbitrary bases or optional flanking regions.

- `__typename` (string, optional)
- `color` (string, optional) — The color of the annotations generated by the Feature Library Item. Must be a valid hex string
- `createdAt` (string, optional) — DateTime the Feature Library Item was created
- `featureLibrary` (FeatureLibraryRef, optional) — The Feature Library the Feature Library Item belongs to
- `featureType` (string, optional, nullable) — The type of the Feature Library Item, like gene, promoter, etc. Note: This is an arbitrary string, not an enum
- `id` (string, optional)
- `matchType` (enum, optional) — The match type of the Feature Library Item. Used to determine how auto-annotate matches are made
  - Allowed values: `NUCLEOTIDE`, `AA_SEQUENCE`
- `modifiedAt` (string, optional) — DateTime the Feature Library Item was last modified
- `name` (string, optional) — The name of the Feature Library Item
- `pattern` (string, optional) — The pattern used for matching during auto-annotation

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### FeatureLibraryRef

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

## Examples

**Request**

```json
{
  "items": [
    {
      "color": "#F58A5E",
      "featureLibraryId": "featlib_cWYhFmxq",
      "matchType": "NUCLEOTIDE",
      "name": "T7 promoter",
      "pattern": "TAATACGACTCACTATAGGG",
      "featureType": "promoter"
    }
  ]
}
```

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "color": "color",
      "createdAt": "createdAt",
      "featureType": "featureType",
      "id": "id",
      "matchType": "NUCLEOTIDE",
      "modifiedAt": "modifiedAt",
      "name": "name",
      "pattern": "pattern"
    }
  ]
}
```

**SDK Code**

```python
import requests

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

payload = { "items": [
        {
            "color": "#F58A5E",
            "featureLibraryId": "featlib_cWYhFmxq",
            "matchType": "NUCLEOTIDE",
            "name": "T7 promoter",
            "pattern": "TAATACGACTCACTATAGGG",
            "featureType": "promoter"
        }
    ] }
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/feature-library-item:batch-create';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"items":[{"color":"#F58A5E","featureLibraryId":"featlib_cWYhFmxq","matchType":"NUCLEOTIDE","name":"T7 promoter","pattern":"TAATACGACTCACTATAGGG","featureType":"promoter"}]}'
};

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