--- title: "Batch update AaSequence" method: PATCH path: "/api/v3/aa-sequence:batch-update" tags: ["AA Sequence"] --- # Batch update AaSequence `PATCH /api/v3/aa-sequence:batch-update` ## Request - Base URL: `https://{tenant_name}.benchling.com` - URL: `https://{tenant_name}.benchling.com/api/v3/aa-sequence:batch-update` - Auth: HTTP bearer Batch update AaSequence synchronously in one transaction. Maximum 25 items per request. ## Request body - object - `items` UpdateAaSequenceInputWithPathParams[], required - `aliases` string[]: Array of aliases - `allowCustomFieldDeletion` boolean: 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. - `aminoAcids` string: Updates the amino acids of the AA sequence when provided. Letters A-Z only (case-insensitive). Invalid characters are rejected. There is a per-tenant limit on sequence length (50,000 characters by default). The request must also include an `annotations` property (use `annotations: []` to clear annotations); that value replaces the sequence's full annotation set. - `annotations` AaAnnotationInputUpdate[]: Replaces the sequence's full annotation set when provided. Include `annotationId` on an entry to update an existing annotation; omit it to create a new one. - `annotationId` string: API ID of an existing annotation on this sequence. Omit to create a new annotation when `annotations` is provided. - `color` string: Hex color when displaying the annotation. For a new annotation, a random color is assigned if omitted. When `annotationId` identifies an existing annotation, omitted `color` is preserved from the prior version. - `end` integer, required: 0-based exclusive end index. For an annotation at the end of the sequence, set `end` to the sequence length (recommended) or `0`; both are accepted on input and stored equivalently. In API responses, `end` is returned as the sequence length, not `0`. - `name` string, required: Name of the annotation. - `notes` string: Text notes on the annotation. For a new annotation, defaults to an empty string if omitted. When `annotationId` identifies an existing annotation, omitted `notes` are preserved from the prior version. - `start` integer, required: 0-based inclusive start index. - `type` string: Feature type of the annotation. For a new annotation, defaults to an empty string if omitted. When `annotationId` identifies an existing annotation, omitted `type` is preserved from the prior version. - `archiveReason` string: Why it is being archived. Required when `archived` is `true`, and not allowed when unarchiving. - `archived` boolean: Set to `true` to archive or `false` to unarchive it. Archiving requires `archiveReason`. - `authorIds` string[] - `customFields` object: Custom fields set on the AA sequence. - `entityRegistryId` string: 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 - `id` string, required: API identifier of the registry item to update. - `name` string: Name of the item. - `namingStrategy` 'NEW_IDS' | 'IDS_FROM_NAMES' | 'DELETE_NAMES' | 'SET_FROM_NAME_PARTS' | 'REPLACE_NAMES_FROM_PARTS' | 'KEEP_NAMES' | 'REPLACE_ID_AND_NAME_FROM_PARTS': Strategy to use for labeling the item in the registry if registering. If one is specified, the entity_registry_id must be unspecified. - `registryId` string, 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` object - `schemaId` string ## Response `200` OK - AaSequenceBatchupdateResponse200 - `items` AaSequence[], required - `__typename` string - `aliases` string[], nullable: Array of aliases - `aminoAcids` string: Amino acids of the AA sequence. - `annotations` string, uri: Annotations marking functional regions, domains, binding sites, post-translational modifications, or other features on the AA sequence. - `archiveReason` string, nullable - `archived` boolean - `createdAt` string, datetime, nullable: DateTime the AA sequence was created. - `customFields` CustomField[], nullable: Custom fields set on the AA sequence. - `__typename` string - `name` string, nullable - `value` string, nullable - `entityRegistryId` string, 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 - `__typename` string - `id` string, api_id - `id` string: ID of the AA sequence. - `modifiedAt` string, datetime, nullable: DateTime the AA sequence was last modified. - `name` string: Name of the item. - `project` ProjectRef - `__typename` string - `id` string, api_id - `registrationOrigin` 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 - `originEntry` DocumentLikeRef - `__typename` string - `id` string, api_id - `registeredAt` string, datetime, nullable - `registry` RegistryRef - `__typename` string - `id` string, api_id - `schema` EntitySchemaRef - `__typename` string - `id` string, api_id - `typedSchema` AaSequenceSchemaRef - `__typename` string - `id` string, api_id - `authors` string, uri, nullable - `creator` PrincipalRef - `__typename` string - `id` string, api_id - `schemaFields` SchemaFieldValue[], nullable - `__typename` string - `fieldDefinition` SchemaFieldDefinitionRef - `__typename` string - `id` string, api_id - `id` string - `linkedEntityId` string, nullable - `value` union: Types of values that Benchling can interpret. - object: A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns). - `__typename` 'ArrayValue', required: Discriminator value: ArrayValue - `value` SingularBenchlingValue[] - union: A union of value types that can appear as elements within an ArrayValue. Identical to BenchlingValue but excludes ArrayValue to prevent nesting. Keep in sync with BenchlingValue. - … - object: A type that represents boolean values. - `__typename` 'BooleanValue', required: Discriminator value: BooleanValue - `value` boolean: The boolean value. - object: A type that represents datetime values. - `__typename` 'DateTimeValue', required: Discriminator value: DateTimeValue - `value` string, datetime: The datetime value with UTC as the timezone. - object: A type that represents date values. - `__typename` 'DateValue', required: Discriminator value: DateValue - `value` string, date: The date value. - object: A type that represents decimal value as strings. - `__typename` 'DecimalValue', required: Discriminator value: DecimalValue - `numericValue` number, double, nullable: Deprecated. The float representation of the decimal value. - `value` string, nullable: The decimal value in a string representation - object: A type that represents integer values. - `__typename` 'IntegerValue', required: Discriminator value: IntegerValue - `value` integer: The integer value. - object: A type that represents JSON values. - `__typename` 'JsonValue', required: Discriminator value: JsonValue - `value` union: The JSON value. - object - string[] - string - number, double - boolean - object: A type that represents a list of links to other objects. - `__typename` 'ObjectLinkListValue', required: Discriminator value: ObjectLinkListValue - `value` LinkableDomainObject[]: 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. - union: A union representing items that can be linked to. If you have a type that can be linked to, it can only be added once it's in beta. - … - object: A type that represents links to other objects. - `__typename` 'ObjectLinkValue', required: Discriminator value: ObjectLinkValue - `value` union: A union representing items that can be linked to. If you have a type that can be linked to, it can only be added once it's in beta. - object: AaSequence variant - … - object: Attachment variant - … - object: Box variant - … - object: Container variant - … - object: CustomEntity variant - … - object: DnaOligo variant - … - object: DnaSequence variant - … - object: DropdownOption variant - … - object: Entry variant - … - object: Inaccessible variant - … - object: Location variant - … - object: MatrixPlate variant - … - object: Mixture variant - … - object: Molecule variant - … - object: OligoConjugate variant - … - object: OligoDuplex variant - … - object: Protein variant - … - object: Result variant - … - object: RnaOligo variant - … - object: RnaSequence variant - … - object: WellPlate variant - … - object: A type that represents text (string) values with an associated URL. - `__typename` string, required - `url` string: The URL associated with the value. Please use `TextValue` if you don't want a URL. - `value` string: The text value. It may or may not be an empty string. - object: A type that represents text (string) values. - `__typename` string, required - `value` string: The text value. It may or may not be an empty string. ## Other responses - `400`: Bad Request - `403`: Forbidden - `404`: Not Found - `409`: Conflict - `429`: Too Many Requests - `500`: Internal Server Error ## Changes - **2026-11-05** `3873a10bf7b8`: 1 breaking, 1 info - added `subschema #1, subschema #8, subschema #9` to the `items/items/schemaFields/items/value/oneOf[subschema #1: BenchlingValue]/` response property `oneOf` list for the response status `200` - removed `subschema #1, subschema #8, subschema #9` from the `items/items/schemaFields/items/value/oneOf[subschema #1: BenchlingValue]/` response property `oneOf` list for the response status `200` [Operation history](https://skmtc.dev/benchling/apis/benchling-api/changes/api/v3/aa-sequence:batch-update/patch.md) --- [API](https://skmtc.dev/benchling/apis/benchling-api.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api/revisions/3873a10bf7b8?raw)