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

# Create and register proteins and components

POST https://{tenant_name}.benchling.com/api/v3/proteins:bulk-create-and-register-proteins-and-components
Content-Type: application/json

Create and register proteins and their component parts (domains, chains, and variable pairs)

Reference: https://docs.benchling.com/docs/api/benchling-api/protein/proteins-and-components-bulk-create

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

- `folderId` (string, required) — The ID of the folder in which the new entities should be created.
- `newComponentConfig` (ProteinsAndComponentsBulkCreateRequestNewComponentConfig, required) — Schema IDs for new component entities created during this request. Applies to all rows in the request.
- `proteinCreateInputs` (list of ProteinsAndComponentsBulkCreateRequestProteinCreateInputsItem, required)
- `proteinSchemaId` (string, required) — The schema ID for the protein entity type.
- `entryId` (string, optional) — The ID of the notebook entry into which the creation results will be embedded upon completion. If omitted, no results are written to a notebook entry.
- `germlineConfigs` (list of ProteinsAndComponentsBulkCreateRequestGermlineConfigsItem, optional, nullable) — A list of germline configs indicating the germline with which to annotate each domain key. This applies to all rows in the request.
- `translationParameters` (ProteinsAndComponentsBulkCreateRequestTranslationParameters, optional) — The translation parameters to use when creating AA sequences. Required if the request contains DNA sequences. May be omitted if the request contains only AA sequences.

## Response

### 202

Job status details

- `pollingUri` (string, required) — A URL to poll for the status of the task.
- `taskId` (string, required)

## Errors

### 400 Proteins and Components Bulk 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 Proteins and Components Bulk 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 Proteins and Components Bulk 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)

### 429 Proteins and Components Bulk 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 Proteins and Components Bulk 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

### ProteinsAndComponentsBulkCreateRequestNewComponentConfig

Schema IDs for new component entities created during this request. Applies to all rows in the request.

- `aaPairSchemaId` (string, required) — Schema ID for creating Amino Acid variable pair entities for this request.
- `dnaChainSchemaId` (string, optional, nullable) — Schema ID for DNA chain sequences created for this request. Required if there are DNA inputs.
- `dnaDomainSchemaId` (string, optional, nullable) — Schema ID for DNA domain sequences created for this request. Required if there are DNA inputs.
- `dnaPairSchemaId` (string, optional, nullable) — Schema ID for creating DNA variable pair entities for this request. Required if there are DNA inputs.

### ProteinsAndComponentsBulkCreateRequestProteinCreateInputsItem

Describes one complete protein and optionally some of the DNA that encodes for it. The input does not necessarily need to contain every domain and every chain defined in the associated proteinSchema, and users of this API are welcome to leave many of them out as long as they meet the following constraint: For every amino acid chain type defined in the proteinSchema, either a) it must occur in the chains array or b) each of its constituent domain types must occur in the domains array, or occur as a component of one of the provided variablePairs. Chains that are not provided will be derived from their constituent domains. Domains that are not provided will be annotated and decomposed based on an analysis of the sequence of the chains containing them.

### ProteinsAndComponentsBulkCreateRequestGermlineConfigsItem

- `domainKey` (ProteinsAndComponentsBulkCreateRequestGermlineConfigsItemDomainKey, required)
- `germlineId` (string, required) — API ID of the germline to use for this domain.

### ProteinsAndComponentsBulkCreateRequestTranslationParameters

The translation parameters to use when creating AA sequences. Required if the request contains DNA sequences. May be omitted if the request contains only AA sequences.

- `geneticCode` (enum, required) — The codon table to use to translate DNA sequences to AA sequences.
  - Allowed values: `STANDARD`, `VERTEBRATE_MITOCHONDRIAL`, `YEAST_MITOCHONDRIAL`, `MOLD_MITOCHONDRIAL`, `INVERTEBRATE_MITOCHONDRIAL`, `CILIATE_NUCLEAR`, `ECHINODERM_MITOCHONDRIAL`, `EUPLOTID_NUCLEAR`, `BACTERIAL_ARCHAEAL`, `ALTERNATIVE_YEAST_NUCLEAR`, `ASCIDIAN_MITOCHONDRIAL`, `ALTERNATIVE_FLATWORM_MITOCHONDRIAL`, `BLEPHARISMA_NUCLEAR`, `CHLOROPHYCEAN_MITOCHONDRIAL`, `TREMATODE_MITOCHONDRIAL`, `SCENEDESMUS_OBLIQUUS_MITOCHONDRIAL`, `THRAUSTOCHYTRIUM_MITOCHONDRIAL`, `PTEROBRANCHIA_MITOCHONDRIAL`, `CANDIDATE_DIVISION_SR1`

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### ProteinsAndComponentsBulkCreateRequestGermlineConfigsItemDomainKey

- `label` (string, required) — The domain label (e.g., "VH", "VL").

## Examples

**Request**

```json
{
  "folderId": "lib_lKsxK6",
  "newComponentConfig": {
    "aaPairSchemaId": "ts_aapair012"
  },
  "proteinCreateInputs": [],
  "proteinSchemaId": "ts_XEUrLw"
}
```

**Response**

```json
{
  "pollingUri": "https://tenant.com/api/v3/tasks/bulk-create-and-register-proteins-and-components/cprotjob:ana_fhlbqd",
  "taskId": "cprotjob:ana_fhlbqd"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/proteins:bulk-create-and-register-proteins-and-components"

payload = {
    "folderId": "lib_lKsxK6",
    "newComponentConfig": { "aaPairSchemaId": "ts_aapair012" },
    "proteinCreateInputs": [],
    "proteinSchemaId": "ts_XEUrLw"
}
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/proteins:bulk-create-and-register-proteins-and-components';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"folderId":"lib_lKsxK6","newComponentConfig":{"aaPairSchemaId":"ts_aapair012"},"proteinCreateInputs":[],"proteinSchemaId":"ts_XEUrLw"}'
};

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