> 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 a consensus nucleotide alignment

POST https://{tenant_name}.benchling.com/api/v3/nucleotide-alignment:create-consensus-alignment
Content-Type: application/json

Create a consensus nucleotide alignment

Reference: https://docs.benchling.com/docs/api/benchling-api/nucleotide-alignment/createconsensusalignment

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

- `algorithm` (enum, required) — Multiple sequence alignment algorithm to use.
  - Allowed values: `MAFFT`, `CLUSTALO`
- `files` (list of AlignmentFileInput, required) — Sequence files to align. Minimum 2, maximum 250.
- `clustaloOptions` (ClustalOOptionsInput, optional) — Options to pass to the ClustalO algorithm, only applicable for ClustalO.
- `mafftOptions` (MafftOptionsInput, optional) — Options to pass to the MAFFT algorithm, only applicable for MAFFT.
- `name` (string, optional) — The name of the alignment. When omitted, a name is automatically generated. If specified, it must contain at least one non-whitespace character. Up to 255 characters.
- `newSequence` (NewSequenceInput, optional) — Specifies a folder in which to create a new NucleotideSequence to store the consensus alignment result. Mutually exclusive with sequenceId.
- `sequenceId` (string, optional) — API ID of an existing empty NucleotideSequence to overwrite with the consensus alignment result. The target sequence must have no bases; requests fail with 'Sequence must be empty' otherwise. Mutually exclusive with newSequence.

## Response

### 202

Task started

- `pollingUri` (string, optional)
- `taskId` (string, optional)

## Errors

### 400 Nucleotide Alignment Create Consensus Alignment 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 Nucleotide Alignment Create Consensus Alignment 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 Nucleotide Alignment Create Consensus Alignment 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 Nucleotide Alignment Create Consensus Alignment 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 Nucleotide Alignment Create Consensus Alignment 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 Nucleotide Alignment Create Consensus Alignment 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

### AlignmentFileInput

- `data` (string, optional) — Base64-encoded file content for the sequence to align. Required when providing name instead of sequenceId.
- `name` (string, optional) — File name for a raw sequence file (for example, an .ab1 trace file). Required when providing data instead of sequenceId.
- `sequenceId` (string, optional) — API ID of an existing NucleotideSequence to align. Mutually exclusive with name and data.

### ClustalOOptionsInput

- `maxGuidetreeIterations` (integer, optional) — Max guide tree iterations within combined iterations. Can be in the range -1 to 5 (-1 = no max).
- `maxHmmIterations` (integer, optional) — Max HMM iterations within combined iterations. Can be in the range -1 to 5 (-1 = no max).
- `mbedGuideTree` (boolean, optional) — Whether mBed-like clustering guide tree should be used (faster to use it).
- `mbedIteration` (boolean, optional) — Whether mBed-like clustering iteration should be used (faster to use it).
- `numCombinedIterations` (integer, optional) — Number of (combined guide-tree/HMM) iterations. Can be in the range 0 to 5.

### MafftOptionsInput

- `adjustDirection` (enum, optional) — Controls whether and how MAFFT auto-detects reverse-complement sequences.
  - Allowed values: `FAST`, `ACCURATE`, `DISABLED`
- `gapExtensionPenalty` (double, optional) — Gap extension penalty.
- `gapOpenPenalty` (double, optional) — Gap open penalty.
- `maxIterations` (integer, optional) — Max refinement iterations. Can be in the range 0 to 100. Not applicable for auto strategy, as it will be selected automatically.
- `retree` (integer, optional) — Tree rebuilding. Only used for 6-mer strategy.
- `strategy` (enum, optional) — MAFFT strategy preset.
  - Allowed values: `AUTO`, `SIXMER`, `LOCALPAIR`, `GLOBALPAIR`

### NewSequenceInput

- `folderId` (string, required) — API ID of the folder in which to create the new NucleotideSequence.

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

## Examples

**Request**

```json
{
  "algorithm": "MAFFT",
  "files": [
    {}
  ]
}
```

**Response**

```json
{
  "pollingUri": "pollingUri",
  "taskId": "taskId"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/nucleotide-alignment:create-consensus-alignment"

payload = {
    "algorithm": "MAFFT",
    "files": [{}]
}
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/nucleotide-alignment:create-consensus-alignment';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"algorithm":"MAFFT","files":[{}]}'
};

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