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

POST https://{tenant_name}.benchling.com/api/v2-beta/datasets
Content-Type: application/json

Create a dataset. Note that a data frame must already exist to create a dataset. The data frame id is required in this request in order to create a dataset.

Reference: https://docs.benchling.com/docs/api/v2-beta/benchling-api-beta/datasets/create-dataset

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

- `customFields` (map from string to CustomField, optional) — Custom field values to set on the file
- `dataFrameId` (string, optional) — ID of the data frame that
- `folderId` (string, optional) — ID of the folder that contains the file
- `name` (string, optional) — Display name for the file
- `study_ids` (list of string, optional, nullable) — The study IDs that the dataset is associated with. If provided, the dataset will be associated with the provided studies. If not provided, the dataset will not be associated with any studies.

## Response

### 200

Created

- `archiveRecord` (ArchiveRecord, optional, nullable) — ArchiveRecord Resource if the dataset is archived. This is null if the dataset is not archived.
- `createdAt` (datetime, optional) — Date and time the dataset was created
- `creator` (DatasetCreator, optional) — UserSummary of the user who created the dataset
- `customFields` (map from string to CustomField, optional) — Custom field values of the dataset
- `dataFrameId` (string, optional) — ID of the data frame to link to this dataset
- `displayId` (string, optional) — User-friendly ID of the dataset
- `folderId` (string, optional) — ID of the folder that contains the dataset
- `id` (string, optional)
- `modifiedAt` (datetime, optional) — Date and time the dataset was last modified
- `name` (string, optional) — The user-facing name for this Dataset.

## Errors

### 400 Bad Request Error

Bad Request

- `error` (BadRequestErrorError, optional)

## Types

### CustomField

- `value` (string, optional)

### ArchiveRecord

- `reason` (string, optional)

### DatasetCreator

UserSummary of the user who created the dataset

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

### BadRequestErrorError

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

## Examples

**Request**

```json
{}
```

**Response**

```json
{
  "archiveRecord": {
    "reason": "Made in error"
  },
  "createdAt": {},
  "creator": {
    "handle": "string",
    "id": "string",
    "name": "string"
  },
  "customFields": {},
  "dataFrameId": "dset_LlDFupKyErxx",
  "displayId": "string",
  "folderId": "lib_bf0636",
  "id": "dataset_LlDFupKyErxx",
  "modifiedAt": {},
  "name": "09-14-2022 01:16:20 PM well plate"
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v2-beta/datasets"

payload = {}
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-beta/datasets';
const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{}'
};

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