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

# Validate a bulk assembly

POST https://{tenant_name}.benchling.com/api/v2-alpha/assemblies:validate
Content-Type: application/json

Validate an assembly prior to finalization to see if it will succeed.

Reference: https://docs.benchling.com/docs/api/v2-alpha/benchling-api-alpha/assemblies/validate-assembly

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

- `assemblyParameters` (AssemblySpecSharedAssemblyParameters, required) — Assembly-wide parameters to describe requirements and procedures for the assembly.
- `bins` (list of AssemblySpecSharedBinsItems, required) — Bins are used to group fragments according to their position in the output construct or add a spacer (i.e. constant) region.
- `constructs` (list of AssemblySpecSharedConstructsItems, required) — Output constructs that should be created.
- `fragments` (list of AssemblySpecSharedFragmentsItems, required) — Fragments to be used in the assembly.
- `topology` (enum, required) — Whether the created constructs should be circular or linear.
  - Allowed values: `CIRCULAR`, `LINEAR`

## Response

### 202

This endpoint launched a [long-running task](https://docs.benchling.com/docs/api/v2/benchling-api/tasks/get-task) and returns the Task ID of the launched task. The task response contains a set of [validation results](#components/schemas/AssemblyValidationResult).

- `taskId` (string, optional)

## Errors

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

## Types

### AssemblySpecSharedAssemblyParameters

Assembly-wide parameters to describe requirements and procedures for the assembly.

- `type`: `CONCATENATION` (CONCATENATION)
  - `parameters` (AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingConcatenationParameters, required)
- `type`: `GIBSON` (GIBSON)
  - `parameters` (AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingGibsonParameters, required)
- `type`: `GOLDEN_GATE` (GOLDEN_GATE)
  - `parameters` (AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingGoldenGateParameters, required)
- `type`: `HOMOLOGY` (HOMOLOGY)
  - `parameters` (AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingHomologyParameters, required)

### AssemblySpecSharedBinsItems

- `binType`: `CONSTANT` (CONSTANT)
  - `id` (string, required) — Unique identifier for the bin.
  - `name` (string, required)
  - `residues` (string, required) — Base pairs or amino acid residues for the spacer/constant.
- `binType`: `FRAGMENT` (FRAGMENT)
  - `id` (string, required) — Unique identifier for the bin.
  - `name` (string, required)
  - `fragmentProductionMethod` (enum, optional)
    - Allowed values: `EXISTING_CUT_SITES`, `EXISTING_HOMOLOGY_REGIONS`, `PRIMER_PAIR`

### AssemblySpecSharedConstructsItems

- `fragments` (list of string, required) — Ordered list of fragment IDs to use in creating the construct, or a special option (SKIP) to indicate a bin should be skipped.
- `id` (string, required)

### AssemblySpecSharedFragmentsItems

- `end` (double, required) — End position of the fragment in the provided input.
- `id` (string, required) — Unique identifier for the fragment.
- `orientation` (enum, required)
  - Allowed values: `FORWARD`, `REVERSE`
- `polymer` (AssemblyPolymerReference, required)
- `start` (double, required) — Start position of the fragment in the provided input.
- `binId` (string, required) — ID of the fragment's bin
- `preferredPrimer3Id` (string, optional) — API identifier of a Benchling oligo to be used as a primer at the 3' end of the fragment.
- `preferredPrimer5Id` (string, optional) — API identifier of a Benchling oligo to be used as a primer at the 5' end of the fragment.
- `restrictionEnzyme3Id` (string, optional) — ID of enzyme used to digest fragment at 3' end
- `restrictionEnzyme5Id` (string, optional) — ID of enzyme used to digest fragment at 5' end

### BadRequestErrorError

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

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingConcatenationParameters

- `fragmentProductionMethod` (enum, required)
  - Allowed values: `SLICE`
- `polymerType` (enum, required)
  - Allowed values: `DNA`, `RNA`, `AA`

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingGibsonParameters

- `fragmentProductionMethod`: `EXISTING_CUT_SITES` (EXISTING_CUT_SITES)
  - `maximumHomologyAndBindingRegionLength` (double, required) — Maximum length, in base pairs, of the primer's binding/homology regions.
  - `minimumBindingRegionMeltingTemperature` (double, required) — Minimum melting temperature of the primer binding region.
  - `minimumHomologyAndBindingRegionLength` (double, required) — Minimum length, in base pairs, of the primer's binding/homology regions.
- `fragmentProductionMethod`: `EXISTING_HOMOLOGY_REGIONS` (EXISTING_HOMOLOGY_REGIONS)
  - `maximumHomologyAndBindingRegionLength` (double, required) — Maximum length, in base pairs, of the primer's binding/homology regions.
  - `minimumBindingRegionMeltingTemperature` (double, required) — Minimum melting temperature of the primer binding region.
  - `minimumHomologyAndBindingRegionLength` (double, required) — Minimum length, in base pairs, of the primer's binding/homology regions.
- `fragmentProductionMethod`: `PRIMER_PAIR` (PRIMER_PAIR)
  - `maximumHomologyAndBindingRegionLength` (double, required) — Maximum length, in base pairs, of the primer's binding/homology regions.
  - `maximumPrimerPairMeltingTemperatureDifference` (double, required) — Maximum difference of melting temperature between both primers in a pair.
  - `minimumBindingRegionMeltingTemperature` (double, required) — Minimum melting temperature of the primer binding region.
  - `minimumHomologyAndBindingRegionLength` (double, required) — Minimum length, in base pairs, of the primer's binding/homology regions.
  - `minimumPrimerMeltingTemperature` (double, required) — Minimum melting temperature of the whole primer.

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingGoldenGateParameters

- `fragmentProductionMethod`: `EXISTING_CUT_SITES` (EXISTING_CUT_SITES)
  - `type2SRestrictionEnzymeId` (string, required)
- `fragmentProductionMethod`: `PRIMER_PAIR` (PRIMER_PAIR)
  - `maximumPrimerPairMeltingTemperatureDifference` (double, required) — Maximum difference of melting temperature between both primers in a pair.
  - `minimumBindingRegionLength` (double, required) — Minimum length of the primer binding region.
  - `minimumBindingRegionMeltingTemperature` (double, required) — Minimum melting temperature of the primer binding region.
  - `preRecognitionSiteBases` (string, required) — Specific base pairs to insert before the type IIS enzyme recognition site.
  - `preRecognitionSiteLength` (double, required) — Number of base pairs to insert before the type IIS enzyme recognition site.
  - `type2SRestrictionEnzymeId` (string, required)

### AssembliesCreateAndFinalizePostRequestBodyContentApplicationJsonSchemaAssemblyParametersDiscriminatorMappingHomologyParameters

- `ambiguousConstructPreference` (enum, required)
  - Allowed values: `USE_LARGER_FRAGMENT_IN_FIRST_BIN`, `USE_SMALER_FRAGMENT_IN_FIRST_BIN`
- `fragmentProductionMethod` (enum, required)
  - Allowed values: `EXISTING_HOMOLOGY_REGIONS`

### AssemblyPolymerReference

- `polymerType`: `AA_SEQUENCE` (AA_SEQUENCE)
  - `proteinId` (string, required) — API identifier for the amino acid sequence.
- `polymerType`: `NUCLEOTIDE_SEQUENCE` (NUCLEOTIDE_SEQUENCE)
  - `sequenceId` (string, required) — API identifier for the nucleotide sequence.

## Examples

**Request**

```json
{
  "assemblyParameters": {
    "type": "GOLDEN_GATE",
    "parameters": {
      "fragmentProductionMethod": "EXISTING_CUT_SITES",
      "type2SRestrictionEnzymeId": "enz_Z1fxwlBi"
    }
  },
  "bins": [
    {
      "binType": "FRAGMENT",
      "id": "string",
      "name": "string"
    }
  ],
  "constructs": [
    {
      "fragments": [
        "string"
      ],
      "id": "string"
    }
  ],
  "fragments": [
    {
      "end": 1.1,
      "id": "string",
      "orientation": "FORWARD",
      "polymer": {
        "polymerType": "NUCLEOTIDE_SEQUENCE",
        "sequenceId": "seq_123"
      },
      "start": 1.1,
      "binId": "bin1"
    }
  ],
  "topology": "CIRCULAR"
}
```

**Response**

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

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2-alpha/assemblies:validate"

payload = {
    "assemblyParameters": {
        "type": "GOLDEN_GATE",
        "parameters": {
            "fragmentProductionMethod": "EXISTING_CUT_SITES",
            "type2SRestrictionEnzymeId": "enz_Z1fxwlBi"
        }
    },
    "bins": [
        {
            "binType": "FRAGMENT",
            "id": "string",
            "name": "string"
        }
    ],
    "constructs": [
        {
            "fragments": ["string"],
            "id": "string"
        }
    ],
    "fragments": [
        {
            "end": 1.1,
            "id": "string",
            "orientation": "FORWARD",
            "polymer": {
                "polymerType": "NUCLEOTIDE_SEQUENCE",
                "sequenceId": "seq_123"
            },
            "start": 1.1,
            "binId": "bin1"
        }
    ],
    "topology": "CIRCULAR"
}
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-alpha/assemblies:validate';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"assemblyParameters":{"type":"GOLDEN_GATE","parameters":{"fragmentProductionMethod":"EXISTING_CUT_SITES","type2SRestrictionEnzymeId":"enz_Z1fxwlBi"}},"bins":[{"binType":"FRAGMENT","id":"string","name":"string"}],"constructs":[{"fragments":["string"],"id":"string"}],"fragments":[{"end":1.1,"id":"string","orientation":"FORWARD","polymer":{"polymerType":"NUCLEOTIDE_SEQUENCE","sequenceId":"seq_123"},"start":1.1,"binId":"bin1"}],"topology":"CIRCULAR"}'
};

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