> 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 Protein POST https://{tenant_name}.benchling.com/api/v3/protein:batch-create Content-Type: application/json Batch create Protein synchronously in one transaction. Maximum 25 items per request. Reference: https://docs.benchling.com/docs/api/benchling-api/protein/batchcreate ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Body (application/json) This endpoint expects an object. - `items` (list of CreateProteinInput, required) ## Response ### 201 Created - `items` (list of Protein, required) ## Errors ### 400 Protein 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 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 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 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 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 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 ### CreateProteinInput - `chains` (list of ProteinChainInput, required) — One entry per chain label on the protein format. Every chain on the format must be included; unknown or duplicate labels are rejected. - `domains` (list of ProteinDomainInput, required) — One entry per domain label on the protein format. Every required domain must be included; unknown or duplicate labels are rejected. Optional domains may be omitted. When included, an optional label must be specified once and applies at every format position for that label. - `folderId` (string, required) - `name` (string, required) — Name of the item. - `schemaId` (string, required) — The ID of the protein schema to create the protein in. The schema's `format` defines required domain and chain labels. - `aliases` (list of string, optional) — Array of aliases - `authorIds` (list of string, optional) - `customFields` (map from string to FieldValueInput, optional) — Custom fields set on the protein. - `entityRegistryId` (string, optional) — Registry ID to assign to the entity. If one is specified, the labeling_strategy must be unspecified. - `namingStrategy` (enum, optional) — Strategy to use for labeling the item in the registry. If one is specified, the entity_registry_id must be unspecified. - Allowed values: `NEW_IDS`, `IDS_FROM_NAMES`, `DELETE_NAMES`, `SET_FROM_NAME_PARTS`, `REPLACE_NAMES_FROM_PARTS`, `KEEP_NAMES`, `REPLACE_ID_AND_NAME_FROM_PARTS` - `registryId` (string, optional, nullable) — A not null value means the entity should be registered. If not null, the value must match the registry of the item's schema. - `schemaFields` (map from string to FieldValueInput, optional) — Values for schema-defined fields on this protein. - `studyIds` (list of string, optional) — Study IDs to add the new protein to. ### Protein - `__typename` (string, optional) - `authors` (string, optional, nullable) - `creator` (PrincipalRef, optional) - `schemaFields` (list of SchemaFieldValue, optional, nullable) — Values for schema-defined fields on this protein. - `aliases` (list of string, optional, nullable) — Array of aliases - `archiveReason` (string, optional, nullable) - `archived` (boolean, optional) - `chains` (list of ProteinChain, optional) — The chains and associated amino acid sequences on the protein. - `createdAt` (string, optional) — DateTime the protein was created. - `customFields` (list of CustomField, optional, nullable) — Custom fields set on the protein. - `domains` (list of ProteinDomain, optional) — The domains and associated amino acid sequences on the protein. - `entityRegistryId` (string, optional, nullable) — The registry-assigned identifier for this item (e.g. its registry ID shown in the UI), present only once the item has been registered. Null if the item is not registered. - `folder` (FolderRef, optional, nullable) - `format` (ProteinFormatRef, optional) — The protein format that defines the structure (domains, chains, interactions) for the protein. - `fullHistory` (string, optional) — `fullHistory` is a superset of `history` that also returns inactive versions that are not part of the current version history. Versions are returned in chronological order (oldest first). - `history` (string, optional) — Only the currently active version lineage, in chronological order (oldest first). If a change was made and then undone by resetting to an earlier version, the version recording that change is not relevant to the current state of the entity, so it is not included in this listing. - `id` (string, optional) — ID of the protein. - `modifiedAt` (string, optional) — DateTime the protein was last modified. - `name` (string, optional) — Name of the item. - `outOfSync` (boolean, optional) — Indicates if constituent domain or chain entities have changed since the protein was last updated. - `outOfSyncReason` (string, optional, nullable) — Any additional information about why the protein is out of sync. - `project` (ProjectRef, optional, nullable) - `registrationOrigin` (RegistrationOrigin, optional, nullable) — Provenance of this item's registration — where and when it was registered. Null if unregistered. - `registry` (RegistryRef, optional, nullable) — The Registry this item belongs to, if registered. Null if unregistered. - `schema` (EntitySchemaRef, optional) — Use typedSchema instead, which returns the per-type schema. - `typedSchema` (ProteinSchemaRef, optional) — Schema reference for this protein. Callers can retrieve the schema separately when they need its field definitions. ### GeneralErrorDetail ### TooManyRequestsErrorBodyDetail ### InternalServerErrorBodyDetail ### ProteinChainInput - `aaSequenceId` (string, required) — API ID of the `AaSequence` entity for this domain or chain. - `label` (string, required) — Chain label from the protein format (see `format` on the protein schema). Must match a label on that format. ### ProteinDomainInput - `aaSequenceId` (string, required) — API ID of the `AaSequence` entity for this domain or chain. - `label` (string, required) — Domain label from the protein format (see `format` on the protein schema). Must match a label on that format. ### FieldValueInput - `value` (any, required) ### PrincipalRef - `__typename` (string, optional) - `id` (string, optional) ### SchemaFieldValue Represents a field value on a schematized object, pairing a `fieldDefinition` (describing the field's type and constraints) with its actual `value` (a `BenchlingValue` such as text, number, date, or link to another object). The value may be null if no value has been set. Used within the `schemaFields` collection on objects that implement `HasSchema` to provide access to all custom field values defined by the object's schema. - `__typename` (string, optional) - `fieldDefinition` (SchemaFieldDefinitionRef, optional) - `id` (string, optional) - `linkedEntityId` (string, optional, nullable) - `value` (SchemaFieldValueValue, optional, nullable) — Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue, ArrayValue ### ProteinChain Represents a polypeptide chain within an `Protein`, containing the domain composition. Each chain has a computed label derived from the format. - `__typename` (string, optional) - `chainPositions` (list of ProteinFormatChainPosition, optional) — Each chain position of this chain in the protein. If a chain has multiplicity > 1, each chain position will be listed here. - `domains` (list of ProteinDomain, optional) — Each domain on the chain, ordered according to the format. - `entity` (AaSequenceRef, optional) — The amino acid sequence entity associated with the chain. - `label` (string, optional) — Unique label for the chain, computed from the format. - `type` (enum, optional) — The type of the chain. - Allowed values: `HEAVY`, `LIGHT`, `NONE`, `ALPHA`, `BETA`, `JOINING` ### CustomField A name-value pair for storing additional metadata on objects that support custom fields. CustomFields provide a flexible way to attach arbitrary string data to entities, containers, datasets, and other Benchling objects without modifying their schemas. Objects that can have custom fields implement the HasCustomFields interface. Unlike schema-defined fields, custom fields are not validated against a schema and can be freely added or modified. - `__typename` (string, optional) - `name` (string, optional, nullable) - `value` (string, optional, nullable) ### ProteinDomain Represents a domain within an `Protein`, containing the actual amino acid sequence for a specific label. Unlike `ProteinFormatDomain` which is a template, `ProteinDomain` is a concrete instance of the domain and links to the underlying amino acid sequence entity. - `__typename` (string, optional) - `domainPositions` (list of ProteinFormatDomainPosition, optional) — Each domain position of this domain in the protein. If this domain appears multiple times in the physical structure of the protein, each domain position will be listed here. - `entity` (AaSequenceRef, optional) — The amino acid sequence entity associated with the domain. - `label` (string, optional) — A human-readable label for the domain. - `type` (enum, optional) — The 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` ### FolderRef - `__typename` (string, optional) - `id` (string, optional) ### ProteinFormatRef - `__typename` (string, optional) - `id` (string, optional) ### ProjectRef - `__typename` (string, optional) - `id` (string, optional) ### RegistrationOrigin Captures the provenance of an entity's registration into the registry. The `originEntry` links to the `DocumentLike` (typically an entry or notebook) from which the entity was registered, providing traceability back to the original experimental context. The `registeredAt` timestamp records when the registration occurred. This information helps scientists understand where registered entities came from and when they were added to the registry. - `__typename` (string, optional) - `originEntry` (DocumentLikeRef, optional, nullable) - `registeredAt` (string, optional, nullable) ### RegistryRef - `__typename` (string, optional) - `id` (string, optional) ### EntitySchemaRef - `__typename` (string, optional) - `id` (string, optional) ### ProteinSchemaRef - `__typename` (string, optional) - `id` (string, optional) ### SchemaFieldDefinitionRef - `__typename` (string, optional) - `id` (string, optional) ### SchemaFieldValueValue ### 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` ### AaSequenceRef - `__typename` (string, optional) - `id` (string, optional) ### 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` ### DocumentLikeRef - `__typename` (string, optional) - `id` (string, optional) ### BooleanValue A type that represents boolean values. - `__typename` (string, optional) - `value` (boolean, optional) — The boolean value. ### DateTimeValue A type that represents datetime values. - `__typename` (string, optional) - `value` (string, optional) — The datetime value with UTC as the timezone. ### DateValue A type that represents date values. - `__typename` (string, optional) - `value` (date, optional) — The date value. ### DecimalValue A type that represents decimal value as strings. - `__typename` (string, optional) - `value` (string, optional, nullable) — The decimal value in a string representation - `numericValue` (double, optional, nullable, deprecated) — Deprecated. The float representation of the decimal value. ### IntegerValue A type that represents integer values. - `__typename` (string, optional) - `value` (integer, optional) — The integer value. ### JsonValue A type that represents JSON values. - `__typename` (string, optional) - `value` (map from string to any, optional) — The JSON value. ### ObjectLinkValue A type that represents links to other objects. - `__typename` (string, optional) - `value` (ObjectRef, optional) — The object that this value links to, or an Inaccessible object if not found with the current permission set. ### ObjectLinkListValue A type that represents a list of links to other objects. - `__typename` (string, optional) - `value` (list of ObjectRef, optional) — The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set. ### TextAndUrlValue A type that represents text (string) values with an associated URL. - `__typename` (string, optional) - `url` (string, optional) — The URL associated with the value. Please use `TextValue` if you don't want a URL. - `value` (string, optional) — The text value. It may or may not be an empty string. ### TextValue A type that represents text (string) values. - `__typename` (string, optional) - `value` (string, optional) — The text value. It may or may not be an empty string. ### ArrayValue A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns). - `__typename` (string, optional) - `value` (list of ArrayValueValueItem, optional) ### ObjectRef - `__typename` (string, optional) - `id` (string, optional) ### ArrayValueValueItem Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue ## Examples **Request** ```json { "items": [ { "chains": [ { "aaSequenceId": "prtn_pQrStUvW", "label": "Heavy" }, { "aaSequenceId": "prtn_xYzAbCdE", "label": "Light" } ], "domains": [ { "aaSequenceId": "prtn_aBcDeFgH", "label": "VH" }, { "aaSequenceId": "prtn_hIjKlMnO", "label": "VL" } ], "folderId": "lib_o2thOLlq", "name": "Example IgG1", "schemaId": "ts_aBcDeFgH", "aliases": [ "mAb-001" ], "schemaFields": { "expression_host": { "value": "CHO" } } } ] } ``` **Response** ```json { "items": [ { "__typename": "__typename", "authors": "authors", "schemaFields": [ {} ], "aliases": [ "aliases" ], "archiveReason": "archiveReason", "archived": true, "chains": [ {} ], "createdAt": "createdAt", "customFields": [ {} ], "domains": [ {} ], "entityRegistryId": "entityRegistryId", "fullHistory": "fullHistory", "history": "history", "id": "id", "modifiedAt": "modifiedAt", "name": "name", "outOfSync": true, "outOfSyncReason": "outOfSyncReason" } ] } ``` **SDK Code** ```python import requests url = "https://{tenant_name}.benchling.com/api/v3/protein:batch-create" payload = { "items": [ { "chains": [ { "aaSequenceId": "prtn_pQrStUvW", "label": "Heavy" }, { "aaSequenceId": "prtn_xYzAbCdE", "label": "Light" } ], "domains": [ { "aaSequenceId": "prtn_aBcDeFgH", "label": "VH" }, { "aaSequenceId": "prtn_hIjKlMnO", "label": "VL" } ], "folderId": "lib_o2thOLlq", "name": "Example IgG1", "schemaId": "ts_aBcDeFgH", "aliases": ["mAb-001"], "schemaFields": { "expression_host": { "value": "CHO" } } } ] } headers = { "Authorization": "Bearer ", "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:batch-create'; const options = { method: 'POST', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"items":[{"chains":[{"aaSequenceId":"prtn_pQrStUvW","label":"Heavy"},{"aaSequenceId":"prtn_xYzAbCdE","label":"Light"}],"domains":[{"aaSequenceId":"prtn_aBcDeFgH","label":"VH"},{"aaSequenceId":"prtn_hIjKlMnO","label":"VL"}],"folderId":"lib_o2thOLlq","name":"Example IgG1","schemaId":"ts_aBcDeFgH","aliases":["mAb-001"],"schemaFields":{"expression_host":{"value":"CHO"}}}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ```