> 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 AaSequence

PATCH https://{tenant_name}.benchling.com/api/v3/aa-sequence/{aa_sequence_id}
Content-Type: application/json

Update an AA sequence.

Reference: https://docs.benchling.com/docs/api/benchling-api/aa-sequence/update

## Authentication

- `Authorization` header (bearer token, required) — Bearer authentication of the form `Bearer <token>`, where token is your auth token.

## Request

### Path parameters

- `aa_sequence_id` (string, required) — ID of the AaSequence.

### 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.
- `aminoAcids` (string, optional) — 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` (list of AaAnnotationInputUpdate, optional) — 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.
- `archiveReason` (string, optional)
- `archived` (boolean, optional)
- `authorIds` (list of string, optional)
- `customFields` (map from string to FieldValueInput, optional) — Custom fields set on the AA 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)
- `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`
- `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)

## 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
- `aminoAcids` (string, optional) — Amino acids of the AA sequence.
- `annotations` (string, optional) — Annotations marking functional regions, domains, binding sites, post-translational modifications, or other features on the AA sequence.
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `createdAt` (string, optional, nullable) — DateTime the AA sequence was created.
- `customFields` (list of CustomField, optional, nullable) — Custom fields set on the AA 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) — Folder containing the AA sequence.
- `id` (string, optional) — ID of the AA sequence.
- `modifiedAt` (string, optional, nullable) — DateTime the AA sequence was last modified.
- `name` (string, optional) — Name of the item.
- `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.
- `typedSchema` (AaSequenceSchemaRef, optional, nullable)

## Errors

### 400 Aa 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 Aa 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 Aa 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 Aa 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 Aa 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 Aa 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

### AaAnnotationInputUpdate

- `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.
- `start` (integer, required) — 0-based inclusive start index.
- `annotationId` (string, optional) — API ID of an existing annotation on this sequence. Omit to create a new annotation when `annotations` is provided.
- `color` (string, optional) — 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.
- `notes` (string, optional) — 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.
- `type` (string, optional) — 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.

### 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

### 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)

### AaSequenceSchemaRef

- `__typename` (string, optional)
- `id` (string, optional)

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### 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": "N-terminal tag",
      "start": 0,
      "annotationId": "prtnann_abc123xy",
      "color": "#4ECDC4",
      "notes": "Updated tag region",
      "type": "Tag"
    },
    {
      "end": 18,
      "name": "Linker region",
      "start": 10,
      "color": "#45B7D1",
      "type": "Linker"
    }
  ],
  "name": "Example recombinant protein (v2)"
}
```

**Response**

```json
{
  "__typename": "__typename",
  "authors": "authors",
  "creator": {
    "__typename": "__typename",
    "id": "id"
  },
  "schemaFields": [
    {
      "__typename": "__typename",
      "id": "id",
      "linkedEntityId": "linkedEntityId"
    }
  ],
  "aliases": [
    "aliases"
  ],
  "aminoAcids": "aminoAcids",
  "annotations": "annotations",
  "archiveReason": "archiveReason",
  "archived": true,
  "createdAt": "createdAt",
  "customFields": [
    {
      "__typename": "__typename",
      "name": "name",
      "value": "value"
    }
  ],
  "entityRegistryId": "entityRegistryId",
  "folder": {
    "__typename": "__typename",
    "id": "id"
  },
  "id": "id",
  "modifiedAt": "modifiedAt",
  "name": "name",
  "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"
  },
  "typedSchema": {
    "__typename": "__typename",
    "id": "id"
  }
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/aa-sequence/aa_sequence_id"

payload = {
    "annotations": [
        {
            "end": 10,
            "name": "N-terminal tag",
            "start": 0,
            "annotationId": "prtnann_abc123xy",
            "color": "#4ECDC4",
            "notes": "Updated tag region",
            "type": "Tag"
        },
        {
            "end": 18,
            "name": "Linker region",
            "start": 10,
            "color": "#45B7D1",
            "type": "Linker"
        }
    ],
    "name": "Example recombinant protein (v2)"
}
headers = {
    "Authorization": "Bearer <token>",
    "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/aa-sequence/aa_sequence_id';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"annotations":[{"end":10,"name":"N-terminal tag","start":0,"annotationId":"prtnann_abc123xy","color":"#4ECDC4","notes":"Updated tag region","type":"Tag"},{"end":18,"name":"Linker region","start":10,"color":"#45B7D1","type":"Linker"}],"name":"Example recombinant protein (v2)"}'
};

try {
  const response = await fetch(url, options);
  const data = await response.json();
  console.log(data);
} catch (error) {
  console.error(error);
}
```