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

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

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

Reference: https://docs.benchling.com/docs/api/benchling-api/protein-format/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 CreateProteinFormatInput, required)

## Response

### 201

Created

- `items` (list of ProteinFormat, required)

## Errors

### 400 Protein Format 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 Protein Format 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 Protein Format 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 Protein Format 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 Protein Format 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 Protein Format 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

### CreateProteinFormatInput

- `veritasName` (string, required) — VERITAS name that defines the protein format structure and visualization. Must be a supported VERITAS format name; invalid or unsupported values are rejected. The structure implied by this name cannot be changed after the format is created. Creating a custom protein format requires Biologics create access for the authenticated user or app.
- `name` (string, optional) — Display name of the protein format. When omitted, the VERITAS name is used. When provided, the name must be non-empty after stripping whitespace, at most 255 characters, and unique among all protein format names in the organization (including built-in format names).

### ProteinFormat

A ProteinFormat defines the structural template for a class of proteins, specifying the arrangement of chains and domains. Formats can be built-in (e.g., IgG1, Fab, scFv) or custom-defined by users.

- `__typename` (string, optional)
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `builtIn` (boolean, optional) — Whether this is an out-of-the-box Benchling-provided format. These formats come pre-loaded and cannot be modified or deleted by users.
- `chainPositions` (list of ProteinFormatChainPosition, optional) — Format chain positions include all physical instances of each chain in a protein of this format.
- `chains` (list of ProteinFormatChain, optional) — The chains of protein entities of this format. Each chain can have multiple chain sites, representing multiple physical instances of the same chain.
- `createdAt` (string, optional) — When the protein format was created.
- `domainPositions` (list of ProteinFormatDomainPosition, optional) — Format domain positions include all physical instances of each domain in a protein of this format.
- `domains` (list of ProteinFormatDomain, optional) — The domains of protein entities of this format. Each domain can have multiple domain sites, representing multiple physical instances of the same domain.
- `id` (string, optional) — API identifier of the protein format. Custom formats use the `abfmt_` prefix; built-in formats use `builtinabfmt_`.
- `modifiedAt` (string, optional) — When the protein format was last modified.
- `name` (string, optional) — The display name of the protein format.
- `originalVeritas` (string, optional, nullable) — The VERITAS string used to create the format.
- `variablePairs` (list of VariablePair, optional) — Variable domain pairs defined on this format (e.g., VH/VL for antibodies). Each pair identifies two variable domains that together form an antigen-binding site.

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### ProteinFormatChainPosition

Defines each instance of a polypeptide chain within a `ProteinFormat`, specifying the chain type and its constituent domains. Each chain position has a unique ref identifier and lists the domain positions (see `ProteinFormatDomainPosition`) that compose it in order from N-terminus to C-terminus. For example, a heavy chain position might reference domain positions [VH, CH1, Hinge, CH2, CH3].

- `__typename` (string, optional)
- `domainPositions` (list of ProteinFormatDomainPosition, optional) — A list of all the domain positions that make up the chain position, in order
- `ref` (integer, optional) — A unique identifier for a physical component (chain or domain) in a protein format. This is used to form a HELM reference that is used in the protein's complex polymer structure.
- `type` (enum, optional) — Type of the chain.
  - Allowed values: `HEAVY`, `LIGHT`, `NONE`, `ALPHA`, `BETA`, `JOINING`

### ProteinFormatChain

A chain in a protein format, representing the slot where a polypeptide chain can be used in an entity of this format. Chains are uniquely identified by their label in the format. Chains can have multiplicity, meaning there are multiple physical instances of the same chain in a protein of this format.

- `__typename` (string, optional)
- `chainPositions` (list of ProteinFormatChainPosition, optional) — A list of all the chain positions of this chain in the format.
- `domains` (list of ProteinFormatDomain, optional) — The domains that compose this chain.
- `label` (string, optional) — A human-readable label for the chain, such as 'Heavy' or 'Light 1'. Chains are labeled with an index only when multiple distinct chains of the same type exist. These labels are unique among distinct chains in a format.
- `type` (enum, optional) — The type of the chain.
  - Allowed values: `HEAVY`, `LIGHT`, `NONE`, `ALPHA`, `BETA`, `JOINING`

### ProteinFormatDomainPosition

Defines a domain position within a `ProteinFormat`, specifying the domain type and identity of each physical domain in the protein format. Each domain position has a unique ref identifier used to construct HELM notation for complex polymer structures. Domain positions are grouped into ProteinFormatDomains, and each group can be uniquely identified by its label, and will be a single amino acid sequence entity in proteins of this format.

- `__typename` (string, optional)
- `optional` (boolean, optional) — Whether this domain is optional in the format. If true, entities of this format may not have this domain.
- `ref` (integer, optional) — A unique identifier for a physical component (chain or domain) in a protein format. This is used to form a HELM reference that is used in the protein's complex polymer structure.
- `type` (enum, optional) — Type of the domain
  - Allowed values: `VL`, `CL`, `VH`, `VHH`, `CH1`, `CH2`, `CH3`, `CH4`, `J`, `H`, `L`, `VA`, `CA`, `VB`, `CB`, `VG`, `CG`, `VD`, `CD`, `F`, `ELEMENT`

### ProteinFormatDomain

A domain in a protein format, representing the slot where an amino acid sequence can be used in an entity of this format. Domains are uniquely identified by their label in the format.

- `__typename` (string, optional)
- `domainPositions` (list of ProteinFormatDomainPosition, optional) — A list of all the domain positions of this domain in the format.
- `label` (string, optional) — A human-readable label for the domain, uniquely identifying the domain within the format.
- `optional` (boolean, optional) — Whether this domain is optional in the format. If true, entities of this format may not have this domain.
- `type` (enum, optional) — The type of the domain (e.g., VH, VL, CH1).
  - Allowed values: `VL`, `CL`, `VH`, `VHH`, `CH1`, `CH2`, `CH3`, `CH4`, `J`, `H`, `L`, `VA`, `CA`, `VB`, `CB`, `VG`, `CG`, `VD`, `CD`, `F`, `ELEMENT`

### VariablePair

Represents a variable domain pair in a protein format. A variable pair represents the two variable domains that together form an antigen-binding site. The domain types depend on the receptor: - Antibodies: VH + VL - TCR alpha/beta: VA + VB - TCR gamma/delta: VG + VD The label is a human-readable identifier for display purposes.

- `__typename` (string, optional)
- `label` (string, optional) — A human-readable label identifying this variable pair within the format.
- `vhVaVg` (ProteinFormatDomain, optional) — The first variable domain in the pair (VH, VA, or VG depending on receptor type).
- `vlVbVd` (ProteinFormatDomain, optional) — The second variable domain in the pair (VL, VB, or VD depending on receptor type).

## Examples

**Request**

```json
{
  "items": [
    {
      "veritasName": "IgG-Fab",
      "name": "IgG-Fab format"
    }
  ]
}
```

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "archiveReason": "archiveReason",
      "archived": true,
      "builtIn": true,
      "chainPositions": [
        {}
      ],
      "chains": [
        {}
      ],
      "createdAt": "createdAt",
      "domainPositions": [
        {}
      ],
      "domains": [
        {}
      ],
      "id": "id",
      "modifiedAt": "modifiedAt",
      "name": "name",
      "originalVeritas": "originalVeritas",
      "variablePairs": [
        {}
      ]
    }
  ]
}
```

**SDK Code**

```python
import requests

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

payload = { "items": [
        {
            "veritasName": "IgG-Fab",
            "name": "IgG-Fab format"
        }
    ] }
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/protein-format:batch-create';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"items":[{"veritasName":"IgG-Fab","name":"IgG-Fab format"}]}'
};

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