---
title: "Create or update a registered AA sequence."
method: PATCH
path: "/aa-sequences/{entity_registry_id}:upsert"
tags: ["aaSequences"]
---

# Create or update a registered AA sequence.

`PATCH /aa-sequences/{entity_registry_id}:upsert`

## Request

- Base URL: `https://{tenant_name}.benchling.com/api/v2`
- URL: `https://{tenant_name}.benchling.com/api/v2/aa-sequences/{entity_registry_id}:upsert`
- Auth: HTTP bearer

Create or update a registered AA sequence.

Schema field links can be populated using entity registry IDs or API IDs. In the `value` field of the `Field` resource, the object `{"entityRegistryId": ENTITY_REGISTRY_ID}` may be provided instead of the API ID if desired (see example value).

## Path parameters

- `entity_registry_id` string, required

## Request body

- AaSequenceUpsert
  - `archiveRecord` ArchiveRecordSet: Currently, we only support setting a null value for archiveRecord, which unarchives the item
  - `fields` FieldsWithResolution
  - `name` string, required: Name of the AA sequence.
  - `registryId` string, required
  - `schemaId` string, required: ID of the AA sequence's schema.
  - `entityRegistryId` string, required: Registry ID of the entity in Benchling.
  - `aliases` string[]: Aliases to add to the AA sequence
  - `aminoAcids` string, required: Amino acids for the AA sequence.
  - `annotations` AaAnnotation[], required: Annotations to create on the AA sequence.
    - `color` string
    - `end` integer: 0-based exclusive end index. The end of the AA sequence is always represented as 0.
    - `id` string
    - `name` string
    - `notes` string
    - `start` integer: 0-based inclusive start index.
    - `type` string
  - `authorIds` string[]: IDs of users to set as the AA sequence's authors.
  - `customFields` CustomFields
  - `folderId` string: ID of the folder containing the AA sequence.

## Response `200`

OK

- AaSequence
  - `aliases` string[]: Array of aliases
  - `aminoAcids` string: Amino acids of the AA sequence.
  - `annotations` AaAnnotation[]: Array of annotation objects on the AA sequence.
    - `color` string
    - `end` integer: 0-based exclusive end index. The end of the AA sequence is always represented as 0.
    - `id` string
    - `name` string
    - `notes` string
    - `start` integer: 0-based inclusive start index.
    - `type` string
  - `apiURL` string, uri: The canonical url of the AA Sequence in the API.
  - `archiveRecord` ArchiveRecord
    - `reason` string
  - `authors` UserSummary[]
    - `handle` string
    - `id` string
    - `name` string
  - `createdAt` string, date-time: DateTime the AA sequence was created.
  - `creator` UserSummary
    - `handle` string
    - `id` string
    - `name` string
  - `customFields` CustomFields
  - `entityRegistryId` string, nullable: Registry ID of the AA sequence if registered.
  - `fields` Fields
  - `folderId` string, nullable: ID of the folder that contains the AA sequence.
  - `id` string: ID of the AA sequence.
  - `length` integer: Number of amino acids in the AA sequence.
  - `modifiedAt` string, date-time: DateTime the AA sequence was last modified.
  - `name` string: Name of the AA sequence.
  - `registrationOrigin` RegistrationOrigin
    - `originEntryId` string, nullable
    - `registeredAt` string, date-time
  - `registryId` string, nullable: Registry the AA sequence is registered in.
  - `schema` SchemaSummary
    - `id` string
    - `name` string
  - `url` string: The path of the web URL, omitting the tenant domain
  - `webURL` string, uri: URL of the AA sequence.

## Other responses

- `400`: Bad Request

---

[API](https://skmtc.dev/benchling/apis/benchling-api-2.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api-2/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api-2/revisions/01d2fa8523cd?raw)