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

# Create RnaOligo

POST https://{tenant_name}.benchling.com/api/v3/rna-oligo
Content-Type: application/json

Create an RNA Oligo in a folder. `name` and `folderId` are required.

## Sequence specification

Provide exactly one of the following:
- `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)

Reference: https://docs.benchling.com/docs/api/benchling-api/rna-oligo/create

## Authentication

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

## Request

### Body (application/json)

This endpoint expects a CreateRnaOligoInput.

- `folderId` (string, required)
- `name` (string, required) — Name of the item.
- `aliases` (list of string, optional) — Array of aliases
- `annotations` (list of OligoAnnotationInput, optional) — Annotations on the Oligo.
- `authorIds` (list of string, optional)
- `bases` (string, optional) — Bases of the Oligo. Mutually exclusive with `helm` and `customNotation`.
- `customFields` (map from string to FieldValueInput, optional) — Custom fields set on the Oligo.
- `customNotation` (string, optional) — 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) — 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. If one is specified, the labeling_strategy must be unspecified.
- `helm` (string, optional) — HELM notation for the oligo sequence and chemical modifications. Requires the modified nucleotides feature to be enabled. Mutually exclusive with `bases` and `customNotation`.
- `namingStrategy` (enum, optional) — Strategy to use for labeling the item in the registry. 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. 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

### 201

Created

- `__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 Oligo.
- `archiveReason` (string, optional, nullable)
- `archived` (boolean, optional)
- `bases` (string, optional) — Bases of the Oligo.
- `canonicalHelm` (string, optional) — Normalized HELM notation for this oligo.
- `createdAt` (string, optional, nullable) — DateTime the Oligo was created.
- `customFields` (list of CustomField, optional, nullable) — Custom fields set on the Oligo.
- `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 oligo.
- `id` (string, optional) — ID of the Oligo.
- `modifiedAt` (string, optional, nullable) — DateTime the Oligo was last modified.
- `modifiedNucleotides` (string, optional) — Modifications applied to this oligo.
- `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` (RnaOligoSchemaRef, optional, nullable)

## Errors

### 400 Rna Oligo Create 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 Oligo Create 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 Oligo Create 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 Oligo Create 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 Oligo Create 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 Oligo Create 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

### OligoAnnotationInput

- `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.
- `type` (string, required) — Feature type of the annotation.
- `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.
- `notes` (string, optional) — Text notes on the annotation. Defaults to an empty string if omitted.

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

### RnaOligoSchemaRef

- `__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.

### 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
{
  "folderId": "lib_o2thOLlq",
  "name": "siRNA guide strand",
  "annotations": [
    {
      "end": 8,
      "name": "Target region",
      "start": 2,
      "type": "target",
      "color": "#FF6B6B",
      "notes": "Gene silencing target"
    }
  ],
  "bases": "AUCGAUCG",
  "schemaFields": {
    "target_gene": {
      "value": "BRCA1"
    }
  },
  "schemaId": "ts_o2thOLlq"
}
```

**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",
  "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/rna-oligo"

payload = {
    "folderId": "lib_o2thOLlq",
    "name": "siRNA guide strand",
    "annotations": [
        {
            "end": 8,
            "name": "Target region",
            "start": 2,
            "type": "target",
            "color": "#FF6B6B",
            "notes": "Gene silencing target"
        }
    ],
    "bases": "AUCGAUCG",
    "schemaFields": { "target_gene": { "value": "BRCA1" } },
    "schemaId": "ts_o2thOLlq"
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/rna-oligo';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"folderId":"lib_o2thOLlq","name":"siRNA guide strand","annotations":[{"end":8,"name":"Target region","start":2,"type":"target","color":"#FF6B6B","notes":"Gene silencing target"}],"bases":"AUCGAUCG","schemaFields":{"target_gene":{"value":"BRCA1"}},"schemaId":"ts_o2thOLlq"}'
};

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