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

# Apply an automation template

POST https://{tenant_name}.benchling.com/api/v3/analysis/{analysis_id}:apply-template
Content-Type: application/json

Apply a published automation template to an Analysis. Populates the Analysis with the template's pipeline steps, substituting the provided data frame and config variable bindings. The Analysis then runs asynchronously. The template must be published before it can be applied. Returns an async task link that can be polled for completion.

Reference: https://docs.benchling.com/docs/api/benchling-api/analysis/applytemplate

## Authentication

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

## Request

### Path parameters

- `analysis_id` (string, required) — ID of the Analysis.

### Headers

- `EARLY-ACCESS` (string, optional) — Set to true to access beta operations via /api/v3.

### Body (application/json)

This endpoint expects an object.

- `dataFrameVariableBindings` (list of AutomationTemplateDataFrameVariableBindingInput, required) — Bindings that map the template's data frame variables (see AutomationTemplateDataFrameVariable) to actual data frames. Each binding specifies which data frame to substitute for a template variable.
- `templateId` (string, required) — ID of the published automation template to apply.
- `templateVariableBindings` (list of AutomationTemplateVariableBindingInput, optional) — Bindings that provide values for the template's config variables (see AutomationTemplateVariable). Every config variable on the template must have a value specified; use a null variableValue to leave a variable empty.

## Response

### 202

Task started

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

## Errors

### 400 Analysis Apply Template 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 Analysis Apply Template 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 Analysis Apply Template 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 Analysis Apply Template 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 Analysis Apply Template 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 Analysis Apply Template 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

### AutomationTemplateDataFrameVariableBindingInput

- `dataFrameId` (string, required) — ID of the DataFrame to substitute for this variable.
- `sourceStepDataId` (string, required) — ID of an existing output AutomationStepData in the target Analysis whose raw data contains the DataFrame identified by dataFrameId.
- `variableId` (string, required) — ID of the AutomationTemplateDataFrameVariable to bind.
- `columnMapping` (map from string to string, optional) — Optional mapping of template column names to actual DataFrame column names. Keys are template column system names; values are the corresponding column system names in the provided DataFrame.

### AutomationTemplateVariableBindingInput

- `variableId` (string, required) — ID of the AutomationTemplateVariable to bind.
- `variableValue` (any, required) — The value for the config variable, as any JSON value.

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

## Examples

**Request**

```json
{
  "dataFrameVariableBindings": [
    {
      "dataFrameId": "dataFrameId",
      "sourceStepDataId": "sourceStepDataId",
      "variableId": "variableId"
    }
  ],
  "templateId": "templateId"
}
```

**Response**

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

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/analysis/analysis_id:apply-template"

payload = {
    "dataFrameVariableBindings": [
        {
            "dataFrameId": "dataFrameId",
            "sourceStepDataId": "sourceStepDataId",
            "variableId": "variableId"
        }
    ],
    "templateId": "templateId"
}
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/analysis/analysis_id:apply-template';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"dataFrameVariableBindings":[{"dataFrameId":"dataFrameId","sourceStepDataId":"sourceStepDataId","variableId":"variableId"}],"templateId":"templateId"}'
};

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