> 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 codon-optimized DNA sequences.

POST https://{tenant_name}.benchling.com/api/v2/dna-sequences:optimize-codons
Content-Type: application/json

Create codon-optimized DNA sequences.

Reference: https://docs.benchling.com/docs/api/v2/benchling-api/dna-sequences/optimize-codons

## 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 an OptimizeCodons.

- `dnaSequenceIds` (list of string, required) — IDs of DNA sequences to codon-optimize.
- `folderId` (string, required) — ID of the folder in which the optimized sequences will be saved.
- `avoidedCutsiteEnzymeIds` (list of string, optional) — List of enzyme IDs whose recognition sites will be avoided when creating the optimized sequence.
- `codonUsageTableId` (string, optional) — ID of the codon usage table representing the target organism.
- `gcContent` (enum, optional, default: ANY) — The amount of GC content in the optimized sequence. LOW is defined as below 0.33, MEDIUM as 0.33-0.66, and HIGH as above 0.66. If neither gcContent nor gcContentRange is specified, the optimization will default to ANY (0-1). Cannot be specified together with gcContentRange.
  - Allowed values: `ANY`, `LOW`, `MEDIUM`, `HIGH`
- `gcContentRange` (OptimizeCodonsGcContentRange, optional) — Custom GC content range for the optimized sequence, specified as decimal values between 0 and 1. The maximum must be greater than the minimum. Cannot be specified together with gcContent.
- `hairpinParameters` (OptimizeCodonsHairpinParameters, optional) — These parameters are applied in the AvoidHairpins specification in DNAChisel. If hairpinParameters is not specified, hairpins will not be avoided.
- `method` (enum, optional, default: MATCH_CODON_USAGE) — The codon optimization algorithm to use. Requires codonUsageTableId to be specified. MATCH_CODON_USAGE selects codons probabilistically based on the organism's codon usage frequencies. USE_BEST_CODON always selects the most frequently used codon for each amino acid.
  - Allowed values: `MATCH_CODON_USAGE`, `USE_BEST_CODON`
- `reducedPatterns` (list of ReducedPattern, optional) — List of patterns to avoid when creating the optimized sequence, on the coding strand only.
- `schemaId` (string, optional) — ID of the optimized DNA sequences' schemas
- `shouldDepleteUridine` (boolean, optional, default: false) — If not specified, the optimization will default to false, and mRNA uridine depletion will not be performed.

## Response

### 202

This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task. When successful, the task has an empty response.

- `taskId` (string, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

## Types

### OptimizeCodonsGcContentRange

Custom GC content range for the optimized sequence, specified as decimal values between 0 and 1. The maximum must be greater than the minimum. Cannot be specified together with gcContent.

- `max` (double, optional) — Maximum GC content ratio (e.g., 0.6 for 60%)
- `min` (double, optional) — Minimum GC content ratio (e.g., 0.4 for 40%)

### OptimizeCodonsHairpinParameters

These parameters are applied in the AvoidHairpins specification in DNAChisel. If hairpinParameters is not specified, hairpins will not be avoided.

- `stem` (integer, optional, default: 20)
- `window` (integer, optional, default: 200)

### ReducedPattern

DNA patterns to avoid during optimization. Supports two formats: 1) DNA base patterns: strings of ATGC bases (case-insensitive, e.g., "ATGC" or "gat") 2) Repeat patterns: format "nxkmer" specifying n repeats of k-sized sequences (e.g., "3x4mer" matches 3 consecutive 4-base repeats). Maximum total length for repeat patterns is 50 bases (n * k ≤ 50). If avoidReverseComplement is true, the pattern's reverse complement will also be avoided. Note: avoidReverseComplement cannot be true for repeat patterns (nxkmer format).

- `avoidReverseComplement` (boolean, optional, default: false)
- `pattern` (string, optional)

### BadRequestErrorError

- `message` (string, optional)
- `type` (enum, optional)
  - Allowed values: `invalid_request_error`
- `userMessage` (string, optional)

## Examples

**Request**

```json
{
  "dnaSequenceIds": [
    "string"
  ],
  "folderId": "string"
}
```

**Response**

```json
{
  "taskId": "string"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2/dna-sequences:optimize-codons"

payload = {
    "dnaSequenceIds": ["string"],
    "folderId": "string"
}
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/v2/dna-sequences:optimize-codons';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"dnaSequenceIds":["string"],"folderId":"string"}'
};

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