> 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 new workflow task group

POST https://{tenant_name}.benchling.com/api/v2/workflow-task-groups
Content-Type: application/json

Create a new workflow task group. If no name is specified, uses the workflow schema name and a unique incrementor separated by a single whitespace.

Reference: https://docs.benchling.com/docs/api/v2/benchling-api/workflow-task-groups/create-workflow-task-group

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

- `folderId` (string, required) — ID of the folder that contains the workflow task group
- `schemaId` (string, required) — The workflow task schema of tasks in this task group
- `name` (string, optional) — The name of the workflow task group
- `watcherIds` (list of string, optional) — IDs of the users watching the workflow task group

## Response

### 201

OK

- `displayId` (string, optional) — User-friendly ID of the workflow task group
- `id` (string, optional) — The ID of the workflow task group
- `name` (string, optional) — The name of the workflow task group
- `archiveRecord` (ArchiveRecord, optional, nullable)
- `createdAt` (string, optional) — The ISO formatted date and time that the task group was created
- `creationOrigin` (CreationOrigin, optional)
- `creator` (UserSummary, optional)
- `folder` (Folder, optional)
- `modifiedAt` (string, optional) — The ISO formatted date and time that the task group was last modified
- `outputs` (list of WorkflowOutputSummary, optional) — The outputs of the workflow task group
- `responsibleTeam` (TeamSummary, optional, nullable)
- `watchers` (list of UserSummary, optional) — The users watching the workflow task group
- `webURL` (string, optional) — URL of the workflow task group
- `workflowTaskSchema` (WorkflowTaskSchemaSummary, optional)
- `workflowTasks` (list of WorkflowTaskSummary, optional) — The input tasks to the workflow task group
- `executionType` (enum, optional) — The method by which the workflow is executed
  - Allowed values: `DIRECT`, `ENTRY`, `FLOWCHART`, `PROCEDURE`, `PROCEDURE_METHOD`, `PROCEDURE_STEP`
- `flowchartConfigVersionId` (string, optional) — The flowchart configuration that this task group uses. This will be null if the task group does not have executionType FLOWCHART.
- `flowchartTaskGroups` (list of WorkflowNodeTaskGroupSummary, optional) — The task groups that are members of the flowchart that this task group is the root of. This will be null this task group is not the root task group of a flowchart (eg if the task group does not have executionType FLOWCHART).
- `nodeConfig` (WorkflowFlowchartNodeConfig, optional) — The node in a Flowchart that this task group is associated with. This will be null if the task group is not part of a flowchart.
- `rootTaskGroup` (WorkflowTaskGroupSummary, optional) — The task group associated with the root node of the flowchart that this task group is a part of. This will be null if the task group is not part of a flowchart.
- `workflowOutputs` (list of WorkflowOutputSummary, optional) — The outputs of the workflow task group

## Errors

### 400 Bad Request Error

Bad request

- `error` (BadRequestErrorError, optional)

## Types

### ArchiveRecord

- `reason` (string, optional)

### CreationOrigin

- `application` (string, optional, nullable)
- `originId` (string, optional, nullable)
- `originModalUuid` (string, optional, nullable)
- `originType` (string, optional, nullable)

### UserSummary

- `handle` (string, optional)
- `id` (string, optional)
- `name` (string, optional)

### Folder

- `archiveRecord` (ArchiveRecord, optional, nullable)
- `id` (string, optional)
- `name` (string, optional)
- `parentFolderId` (string, optional, nullable) — ID of the parent folder, if it exists
- `projectId` (string, optional) — ID of the containing project

### WorkflowOutputSummary

- `displayId` (string, optional) — User-friendly ID of the workflow task group
- `id` (string, optional) — The ID of the workflow output

### TeamSummary

- `id` (string, optional)
- `name` (string, optional)

### WorkflowTaskSchemaSummary

- `id` (string, optional) — The ID of the workflow task schema
- `name` (string, optional) — The name of the workflow task schema

### WorkflowTaskSummary

- `displayId` (string, optional) — User-friendly ID of the workflow task
- `id` (string, optional) — The ID of the workflow task

### WorkflowNodeTaskGroupSummary

- `displayId` (string, optional) — User-friendly ID of the workflow task group
- `id` (string, optional) — The ID of the workflow task group
- `name` (string, optional) — The name of the workflow task group
- `nodeConfigId` (string, optional) — The node in a Flowchart that this task group is associated with. This will be null if the task group is not part of a flowchart.

### WorkflowFlowchartNodeConfig

- `id` (string, optional) — The ID of the workflow flowchart node config
- `nodeDetails` (WorkflowFlowchartNodeConfigNodeDetails, optional)
- `nodeType` (enum, optional) — The type associated with the node config
  - Allowed values: `ROOT`, `OUTPUT`, `TASK`, `ROUTER`, `END`

### WorkflowTaskGroupSummary

- `displayId` (string, optional) — User-friendly ID of the workflow task group
- `id` (string, optional) — The ID of the workflow task group
- `name` (string, optional) — The name of the workflow task group

### BadRequestErrorError

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

### WorkflowFlowchartNodeConfigNodeDetails

- `nodeType`: `END` (END)
  - `id` (string, optional) — The ID of the workflow flowchart end node config details
  - `name` (string, optional) — The name of the end node
- `nodeType`: `OUTPUT` (OUTPUT)
  - `id` (string, optional) — The ID of the workflow output node config details
  - `outputSchema` (SchemaSummary, optional)
- `nodeType`: `ROOT` (ROOT)
  - `id` (string, optional) — The ID of the workflow root node config details
  - `rootTaskSchema` (WorkflowTaskSchemaSummary, optional)
- `nodeType`: `ROUTER` (ROUTER)
  - `id` (string, optional) — The ID of the workflow router node config details
  - `name` (string, optional) — The name of the router node
  - `routerFunctions` (list of WorkflowRouterFunction, optional) — Router functions associated with this router node
- `nodeType`: `TASK` (TASK)
  - `id` (string, optional) — The ID of the workflow task node config details
  - `taskSchema` (WorkflowTaskSchemaSummary, optional)

### SchemaSummary

- `id` (string, optional)
- `name` (string, optional)

### WorkflowRouterFunction

- `edgeConfigId` (string, optional) — The ID of the workflow flowchart edge config associated with this function
- `id` (string, optional) — The function associated with a router node
- `isDefault` (any, optional)
- `name` (string, optional) — The name of a function associated with a router node

## Examples

**Request**

```json
{
  "folderId": "string",
  "schemaId": "prstsch_KnR9iVum"
}
```

**Response**

```json
{
  "displayId": "string",
  "id": "prs_giVNQcTL",
  "name": "string",
  "archiveRecord": {
    "reason": "Made in error"
  },
  "createdAt": "2020-08-01T00:00:00.000Z",
  "creationOrigin": {
    "application": "string",
    "originId": "string",
    "originModalUuid": "string",
    "originType": "string"
  },
  "creator": {
    "handle": "string",
    "id": "string",
    "name": "string"
  },
  "folder": {
    "archiveRecord": {
      "reason": "Made in error"
    },
    "id": "string",
    "name": "string",
    "parentFolderId": "string",
    "projectId": "string"
  },
  "modifiedAt": "2020-08-01T00:00:00.000Z",
  "outputs": [
    {
      "displayId": "string",
      "id": "wfout_5cJLQKVF"
    }
  ],
  "responsibleTeam": {
    "id": "string",
    "name": "string"
  },
  "watchers": [
    {
      "handle": "string",
      "id": "string",
      "name": "string"
    }
  ],
  "webURL": "string",
  "workflowTaskSchema": {
    "id": "string",
    "name": "string"
  },
  "workflowTasks": [
    {
      "displayId": "string",
      "id": "wftask_OnnsW08k"
    }
  ],
  "executionType": "DIRECT",
  "flowchartConfigVersionId": "wffccv_giVNQcAF",
  "flowchartTaskGroups": [
    {
      "displayId": "string",
      "id": "prs_giVNQcTL",
      "name": "string",
      "nodeConfigId": "wffcnc_giVNQcTL"
    }
  ],
  "nodeConfig": {
    "id": "string",
    "nodeDetails": {
      "nodeType": "ROOT",
      "id": "wfrnd_hbVNQcEM",
      "rootTaskSchema": {
        "id": "string",
        "name": "string"
      }
    },
    "nodeType": "ROOT"
  },
  "rootTaskGroup": {
    "displayId": "string",
    "id": "prs_giVNQcTL",
    "name": "string"
  },
  "workflowOutputs": [
    {
      "displayId": "string",
      "id": "wfout_5cJLQKVF"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2/workflow-task-groups"

payload = {
    "folderId": "string",
    "schemaId": "prstsch_KnR9iVum"
}
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/workflow-task-groups';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"folderId":"string","schemaId":"prstsch_KnR9iVum"}'
};

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