> 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. # Update RnaSequence PATCH https://{tenant_name}.benchling.com/api/v3/rna-sequence/{rna_sequence_id} Content-Type: application/json Update an RNA sequence. The `id` path parameter identifies the RNA sequence to update. ## Sequence specification To replace the sequence, provide exactly one of the following. Omit all sequence fields to keep the existing sequence. - `bases` — plain nucleotide sequence - `helm` — HELM notation (requires the modified nucleotides feature to be enabled) - `customNotation` with `customNotationId` — vendor-specific notation (requires custom syntaxes to be enabled; both fields must be set together) ## Updating bases When replacing `bases`, include every sequence feature collection that already exists on the sequence: `annotations`, `translations`, `primers`, and `parts`. Provide the updated values or an empty array (`[]`) to clear a collection. Omitting a key that has existing data returns `400`. ## Chemical modifications When switching from HELM or custom notation to plain `bases` on a sequence with chemical modifications, include an empty `helm` or `customNotation` string to clear the existing modifications. Updating `bases` alone returns `400`. Reference: https://docs.benchling.com/docs/api/benchling-api/rna-sequence/update ## Authentication - `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer `, where token is your auth token. ## Request ### Path parameters - `rna_sequence_id` (string, required) — ID of the RnaSequence. ### Body (application/json) This endpoint expects an object. - `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 RnaAnnotationInput, optional) — Annotations on the RNA 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 RNA sequence. Mutually exclusive with `helm` and `customNotation`. - `customFields` (map from string to FieldValueInput, optional) — Custom fields set on the RNA sequence. - `customNotation` (string, optional, nullable) — Sequence in a vendor-specific custom notation syntax. Requires custom syntaxes to be enabled. When `customNotation` is set, `customNotationId` is required. Mutually exclusive with `bases` and `helm`. - `customNotationId` (string, optional, nullable) — ID of the custom notation syntax used to interpret `customNotation`. When `customNotation` is set, `customNotationId` is required; omit both when using `bases` or `helm`. - `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) - `helm` (string, optional) — HELM notation for the RNA sequence and chemical modifications. Requires the modified nucleotides feature to be enabled. Mutually exclusive with `bases` and `customNotation`. - `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 RnaPartInput, optional) — Part features linking regions of this sequence to other RNA sequences. - `primers` (list of PrimerInput, optional) — Primer bind features on the RNA 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 RnaTranslationInput, optional) — Translation annotations present on the RNA sequence. Translations may be one region or split across multiple regions. Translations on parts are not included. ## Response ### 200 OK - `__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 RNA 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 RNA sequence. - `canonicalHelm` (string, optional) — Normalized HELM notation for this RNA sequence. - `createdAt` (string, optional, nullable) - `customFields` (list of CustomField, optional, nullable) — Custom fields set on the RNA 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) - `modifiedAt` (string, optional, nullable) - `modifiedNucleotides` (string, optional) — Modifications applied to this RNA sequence. - `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 RNA sequences. - `primers` (string, optional) — Primer bind features on the RNA 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. - `translations` (string, optional) — Translation annotations present on the RNA sequence. Translations may be one region or split across multiple regions. Translations on parts are not included. - `typedSchema` (RnaSequenceSchemaRef, optional, nullable) ## Errors ### 400 Rna Sequence 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 Rna Sequence 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 Rna Sequence 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 Rna Sequence 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 Rna Sequence 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 Rna Sequence 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 ### RnaAnnotationInput - `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. - `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) ### RnaPartInput - `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) — RNA sequence this part refers to. - `start` (integer, required) — 0-based inclusive start index. ### 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` ### RnaTranslationInput - `regions` (list of TranslationRegionInput, required) — Array of regions to translate. For single-region translations, provide one element. - `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) ### RnaSequenceSchemaRef - `__typename` (string, optional) - `id` (string, optional) ### GeneralErrorDetail ### TooManyRequestsErrorBodyDetail ### InternalServerErrorBodyDetail ### 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 { "annotations": [ { "end": 10, "name": "Updated target region", "start": 0, "color": "#4ECDC4", "notes": "Updated silencing target", "type": "target" } ], "bases": "AUCGAUCGAUCGAUCGAUCGAUCG", "name": "Updated CRISPR guide RNA", "parts": [ { "end": 6, "sequenceId": "seq_jdf8BV24", "start": 0 } ], "primers": [ { "location": { "locationType": "start_and_end", "end": 8, "start": 2 }, "oligoId": "seq_laGnl8vB", "strand": "REVERSE" } ], "schemaFields": { "application": { "value": "CRISPR" }, "target_gene": { "value": "BRCA1" } }, "translations": [ { "regions": [ { "end": 9, "start": 1 } ], "geneticCode": "STANDARD", "name": "Updated ORF fragment", "translateFirstCodonToMethionine": false } ] } ``` **Response** ```json { "__typename": "__typename", "authors": "authors", "creator": { "__typename": "__typename", "id": "id" }, "schemaFields": [ { "__typename": "__typename", "id": "id", "linkedEntityId": "linkedEntityId" } ], "aliases": [ "aliases" ], "annotations": "annotations", "archiveReason": "archiveReason", "archived": true, "bases": "bases", "canonicalHelm": "canonicalHelm", "createdAt": "createdAt", "customFields": [ { "__typename": "__typename", "name": "name", "value": "value" } ], "entityRegistryId": "entityRegistryId", "folder": { "__typename": "__typename", "id": "id" }, "id": "id", "modifiedAt": "modifiedAt", "modifiedNucleotides": "modifiedNucleotides", "name": "name", "nucleotideAlignments": "nucleotideAlignments", "parts": "parts", "primers": "primers", "project": { "__typename": "__typename", "id": "id" }, "registrationOrigin": { "__typename": "__typename", "originEntry": { "__typename": "__typename", "id": "id" }, "registeredAt": "registeredAt" }, "registry": { "__typename": "__typename", "id": "id" }, "schema": { "__typename": "__typename", "id": "id" }, "translations": "translations", "typedSchema": { "__typename": "__typename", "id": "id" } } ``` **SDK Code** ```python import requests url = "https://{tenant_name}.benchling.com/api/v3/rna-sequence/rna_sequence_id" payload = { "annotations": [ { "end": 10, "name": "Updated target region", "start": 0, "color": "#4ECDC4", "notes": "Updated silencing target", "type": "target" } ], "bases": "AUCGAUCGAUCGAUCGAUCGAUCG", "name": "Updated CRISPR guide RNA", "parts": [ { "end": 6, "sequenceId": "seq_jdf8BV24", "start": 0 } ], "primers": [ { "location": { "locationType": "start_and_end", "end": 8, "start": 2 }, "oligoId": "seq_laGnl8vB", "strand": "REVERSE" } ], "schemaFields": { "application": { "value": "CRISPR" }, "target_gene": { "value": "BRCA1" } }, "translations": [ { "regions": [ { "end": 9, "start": 1 } ], "geneticCode": "STANDARD", "name": "Updated ORF 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/rna-sequence/rna_sequence_id'; const options = { method: 'PATCH', headers: {Authorization: 'Bearer ', 'Content-Type': 'application/json'}, body: '{"annotations":[{"end":10,"name":"Updated target region","start":0,"color":"#4ECDC4","notes":"Updated silencing target","type":"target"}],"bases":"AUCGAUCGAUCGAUCGAUCGAUCG","name":"Updated CRISPR guide RNA","parts":[{"end":6,"sequenceId":"seq_jdf8BV24","start":0}],"primers":[{"location":{"locationType":"start_and_end","end":8,"start":2},"oligoId":"seq_laGnl8vB","strand":"REVERSE"}],"schemaFields":{"application":{"value":"CRISPR"},"target_gene":{"value":"BRCA1"}},"translations":[{"regions":[{"end":9,"start":1}],"geneticCode":"STANDARD","name":"Updated ORF fragment","translateFirstCodonToMethionine":false}]}' }; try { const response = await fetch(url, options); const data = await response.json(); console.log(data); } catch (error) { console.error(error); } ```