> 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 update DnaSequence PATCH https://{tenant_name}.benchling.com/api/v3/dna-sequence:batch-update Content-Type: application/json Batch update DnaSequence synchronously in one transaction. Maximum 25 items per request. Reference: https://docs.benchling.com/docs/api/benchling-api/dna-sequence/batchupdate ## 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 UpdateDnaSequenceInputWithPathParams, required) ## Response ### 200 OK - `items` (list of DnaSequence, required) ## Errors ### 400 Dna Sequence Batch Update 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 Dna Sequence Batch Update 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 Dna Sequence Batch Update 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 Dna Sequence Batch Update 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 Dna Sequence Batch Update 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 Dna Sequence Batch Update 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 ### UpdateDnaSequenceInputWithPathParams - `id` (string, required) — API identifier of the registry item to update. - `aliases` (list of string, optional) — Array of aliases - `allowCustomFieldDeletion` (boolean, optional) — When true, custom fields present on the entity but omitted from the update payload will be deleted. When false or omitted, omitting existing custom fields is an error. Defaults to false. - `annotations` (list of NucleotideAnnotationInput, optional) — Annotations on the DNA sequence, not including translations or primers. Annotations on parts are not included. - `archiveReason` (string, optional) - `archived` (boolean, optional) - `authorIds` (list of string, optional) - `bases` (string, optional) — Bases of the forward strand of the DNA sequence. - `customFields` (map from string to FieldValueInput, optional) — Custom fields set on the DNA sequence. - `entityRegistryId` (string, optional) — Registry ID to assign to the entity. When registering, specifying this value sets the registry ID of the entity. When already registered, specifying this value updates the entity's registry ID. If set, naming_strategy must be unspecified. - `folderId` (string, optional) - `isCircular` (boolean, optional) — Whether the sequence forms a closed loop, with the last base connecting back to the first. - `name` (string, optional) — Name of the item. - `namingStrategy` (enum, optional) — Strategy to use for labeling the item in the registry if registering. 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` - `parts` (list of NucleotidePartInput, optional) — Part features linking regions of this sequence to other nucleotide sequences. - `primers` (list of PrimerInput, optional) — Primer bind features on the DNA sequence. Primers on parts are not included. - `registryId` (string, optional, nullable) — A not null value means the entity should be registered. A null value means it should be unregistered. If not null, the value must match the registry of the item's schema. - `schemaFields` (map from string to FieldValueInput, optional) - `schemaId` (string, optional) - `translations` (list of TranslationInput, optional) — Translation annotations present on the DNA sequence. Translations may be one region or split across multiple regions. Translations on parts are not included. ### DnaSequence - `__typename` (string, optional) - `authors` (string, optional, nullable) - `creator` (PrincipalRef, optional, nullable) - `schemaFields` (list of SchemaFieldValue, optional, nullable) - `aliases` (list of string, optional, nullable) — Array of aliases - `annotations` (string, optional) — Annotations on the DNA sequence, not including translations or primers. Annotations on parts are not included. - `archiveReason` (string, optional, nullable) - `archived` (boolean, optional) - `bases` (string, optional) — Bases of the forward strand of the DNA sequence. - `createdAt` (string, optional, nullable) - `customFields` (list of CustomField, optional) — Custom fields set on the DNA sequence. - `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) - `id` (string, optional) - `isCircular` (boolean, optional) — Whether the DNA sequence is circular or linear. - `modifiedAt` (string, optional, nullable) - `name` (string, optional) — Name of the item. - `nucleotideAlignments` (string, optional) — Nucleotide alignments that use this sequence as the reference sequence. For template alignments, this is the template sequence; for consensus alignments, this is the derived consensus sequence. - `parts` (string, optional) — Part features linking regions of this sequence to other nucleotide sequences. - `primers` (string, optional) — Primer bind features on the DNA sequence. Primers on parts are not included. - `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, nullable) — Use typedSchema instead, which returns the per-type schema. - `startIndex` (integer, optional) — Starting index for the sequence residues of linear DNA sequences. Implicitly 1 for other sequence types. - `translations` (string, optional) — Translation annotations present on the DNA sequence. Translations may be one region or split across multiple regions. Translations on parts are not included. - `typedSchema` (DnaSequenceSchemaRef, optional, nullable) ### GeneralErrorDetail ### TooManyRequestsErrorBodyDetail ### InternalServerErrorBodyDetail ### NucleotideAnnotationInput - `end` (integer, required) — 0-based exclusive end index. For ranges ending at the sequence end, API responses return `sequenceLength`, never `0`. On input, `sequenceLength` or `0` may be used. - `name` (string, required) — Name of the annotation. - `start` (integer, required) — 0-based inclusive start index. - `strand` (enum, required) — Strand for this annotation; `FORWARD`, `REVERSE`, or `STRANDLESS`. - Allowed values: `FORWARD`, `REVERSE`, `STRANDLESS` - `color` (string, optional) — Hex color when displaying the annotation. A random color is assigned if omitted. - `customFields` (list of CustomFieldInput, optional) — Custom fields on the annotation. Each field name may be at most 1024 characters and each value at most 2712 characters. - `notes` (string, optional) — Text notes on the annotation. Defaults to an empty string if omitted. - `type` (string, optional) — Feature type of the annotation. ### FieldValueInput - `value` (any, required) ### NucleotidePartInput - `end` (integer, required) — 0-based exclusive end index. For ranges ending at the sequence end, API responses return `sequenceLength`, never `0`. On input, `sequenceLength` or `0` may be used. - `sequenceId` (string, required) — Nucleotide sequence this part refers to. - `start` (integer, required) — 0-based inclusive start index. - `strand` (enum, optional) — Strand for this part; `FORWARD` or `REVERSE`. Defaults to `FORWARD` if omitted. - Allowed values: `FORWARD`, `REVERSE` ### PrimerInput - `location` (LocationInput, required) — Binding location on the sequence. - `oligoId` (string, required) — Linked Oligo entity, which holds the name, bases, and color for this primer bind site. - `strand` (enum, required) — Strand for this primer; `FORWARD` or `REVERSE`. - Allowed values: `FORWARD`, `REVERSE` ### TranslationInput - `regions` (list of TranslationRegionInput, required) — Array of regions to translate. For single-region translations, provide one element. - `strand` (enum, required) — Strand for this translation; `FORWARD` or `REVERSE`. - Allowed values: `FORWARD`, `REVERSE` - `color` (string, optional) — Hex color when displaying the translation. Defaults to light blue (`#84B0DC`) if omitted. - `customFields` (list of CustomFieldInput, optional) — Custom fields on the translation. - `geneticCode` (enum, optional) — Genetic code for the translation. Defaults to `STANDARD` if omitted. Genetic codes with ambiguous stop codons are not supported: `BLASTOCRITHIDIA_NUCLEAR`, `CONDYLOSTOMA_NUCLEAR`, `KARYORELICT_NUCLEAR`. - Allowed values: `STANDARD`, `VERTEBRATE_MITOCHONDRIAL`, `YEAST_MITOCHONDRIAL`, `MOLD_PROTOZOAN_COELENTERATE_MITOCHONDRIAL_MYCOPLASMA_SPIROPLASMA`, `INVERTEBRATE_MITOCHONDRIAL`, `CILIATE_DASYCLADACEAN_HEXAMITA_NUCLEAR`, `ECHINODERM_FLATWORM_MITOCHONDRIAL`, `EUPLOTID_NUCLEAR`, `BACTERIAL_ARCHAEAL_PLANT_PLASTID`, `ALTERNATIVE_YEAST_NUCLEAR`, `ASCIDIAN_MITOCHONDRIAL`, `ALTERNATIVE_FLATWORM_MITOCHONDRIAL`, `CHLOROPHYCEAN_MITOCHONDRIAL`, `TREMATODE_MITOCHONDRIAL`, `SCENEDESMUS_OBLIQUUS_MITOCHONDRIAL`, `THRAUSTOCHYTRIUM_MITOCHONDRIAL`, `RHABDOPLEURIDAE_MITOCHONDRIAL`, `CANDIDATE_DIVISION_SR1_GRACILIBACTERIA`, `PACHYSOLEN_TANNOPHILUS_NUCLEAR`, `MESODINIUM_NUCLEAR`, `PERITRICH_NUCLEAR`, `CEPHALODISCIDAE_MITOCHONDRIAL_UAA_TYR` - `name` (string, optional) — Name of the translation. - `notes` (string, optional) — Text notes on the translation. Defaults to an empty string if omitted. - `translateFirstCodonToMethionine` (boolean, optional) — Whether or not the first codon has been forced to be translated as methionine. Defaults to false if omitted. ### 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 ### 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) ### FolderRef - `__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) ### DnaSequenceSchemaRef - `__typename` (string, optional) - `id` (string, optional) ### CustomFieldInput - `name` (string, required) — Name of the custom field. - `value` (string, optional) — Value of the custom field. Defaults to an empty string if omitted. ### LocationInput - `locationType` (enum, required) — Discriminator for primer binding location. Use `start_and_end` for start/end coordinates, or `bind_and_overhang` for bind position and overhang length. - Allowed values: `bind_and_overhang`, `start_and_end` - `bindPosition` (integer, optional) — 0-based index of the base at the 3' end of the binding region. - `overhangLength` (integer, optional) — Number of 5' primer bases that are not part of the binding region. - `end` (integer, optional) — 0-based exclusive end of the binding region. For ranges ending at the sequence end, API responses return `sequenceLength`, never `0`. On input, `sequenceLength` or `0` may be used. - `start` (integer, optional) — 0-based inclusive start of the binding region. ### TranslationRegionInput - `end` (integer, required) — 0-based exclusive end index. For ranges ending at the sequence end, API responses return `sequenceLength`, never `0`. On input, `sequenceLength` or `0` may be used. - `start` (integer, required) — 0-based inclusive start index. ### SchemaFieldDefinitionRef - `__typename` (string, optional) - `id` (string, optional) ### SchemaFieldValueValue ### 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": [ { "id": "seq_9CYiCggY", "annotations": [ { "end": 8, "name": "Updated CMV promoter", "start": 0, "strand": "FORWARD", "color": "#4ECDC4", "notes": "Updated promoter region", "type": "promoter" } ], "bases": "ATGCATGCATGCATGCATGCATGCATGC", "isCircular": true, "name": "Updated pUC19 cloning vector", "parts": [ { "end": 6, "sequenceId": "seq_jdf8BV24", "start": 0, "strand": "REVERSE" } ], "primers": [ { "location": { "locationType": "start_and_end", "end": 8, "start": 2 }, "oligoId": "seq_laGnl8vB", "strand": "REVERSE" } ], "schemaFields": { "backbone_type": { "value": "Plasmid" }, "resistance_marker": { "value": "Kanamycin" } }, "translations": [ { "regions": [ { "end": 9, "start": 1 } ], "strand": "FORWARD", "geneticCode": "STANDARD", "name": "Updated LacZ alpha fragment", "translateFirstCodonToMethionine": false } ] } ] } ``` **Response** ```json { "items": [ { "__typename": "__typename", "authors": "authors", "schemaFields": [ {} ], "aliases": [ "aliases" ], "annotations": "annotations", "archiveReason": "archiveReason", "archived": true, "bases": "bases", "createdAt": "createdAt", "customFields": [ {} ], "entityRegistryId": "entityRegistryId", "id": "id", "isCircular": true, "modifiedAt": "modifiedAt", "name": "name", "nucleotideAlignments": "nucleotideAlignments", "parts": "parts", "primers": "primers", "startIndex": 1, "translations": "translations" } ] } ``` **SDK Code** ```python import requests url = "https://{tenant_name}.benchling.com/api/v3/dna-sequence:batch-update" payload = { "items": [ { "id": "seq_9CYiCggY", "annotations": [ { "end": 8, "name": "Updated CMV promoter", "start": 0, "strand": "FORWARD", "color": "#4ECDC4", "notes": "Updated promoter region", "type": "promoter" } ], "bases": "ATGCATGCATGCATGCATGCATGCATGC", "isCircular": True, "name": "Updated pUC19 cloning vector", "parts": [ { "end": 6, "sequenceId": "seq_jdf8BV24", "start": 0, "strand": "REVERSE" } ], "primers": [ { "location": { "locationType": "start_and_end", "end": 8, "start": 2 }, "oligoId": "seq_laGnl8vB", "strand": "REVERSE" } ], "schemaFields": { "backbone_type": { "value": "Plasmid" }, "resistance_marker": { "value": "Kanamycin" } }, "translations": [ { "regions": [ { "end": 9, "start": 1 } ], "strand": "FORWARD", "geneticCode": "STANDARD", "name": "Updated LacZ alpha fragment", "translateFirstCodonToMethionine": False } ] } ] } headers = { "Authorization": "Bearer ", "Content-Type": "application/json" } response = requests.patch(url, json=payload, headers=headers) print(response.json()) ``` ```javascript const url = 'https://{tenant_name}.benchling.com/api/v3/dna-sequence:batch-update'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"items":[{"id":"seq_9CYiCggY","annotations":[{"end":8,"name":"Updated CMV promoter","start":0,"strand":"FORWARD","color":"#4ECDC4","notes":"Updated promoter region","type":"promoter"}],"bases":"ATGCATGCATGCATGCATGCATGCATGC","isCircular":true,"name":"Updated pUC19 cloning vector","parts":[{"end":6,"sequenceId":"seq_jdf8BV24","start":0,"strand":"REVERSE"}],"primers":[{"location":{"locationType":"start_and_end","end":8,"start":2},"oligoId":"seq_laGnl8vB","strand":"REVERSE"}],"schemaFields":{"backbone_type":{"value":"Plasmid"},"resistance_marker":{"value":"Kanamycin"}},"translations":[{"regions":[{"end":9,"start":1}],"strand":"FORWARD","geneticCode":"STANDARD","name":"Updated LacZ alpha fragment","translateFirstCodonToMethionine":false}]}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ```