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

# Batch update ScratchFile

PATCH https://{tenant_name}.benchling.com/api/v3/scratch-file:batch-update
Content-Type: application/json

Batch update ScratchFile synchronously in one transaction. Maximum 25 items per request.

Reference: https://docs.benchling.com/docs/api/benchling-api/scratch-file/batchupdate

## Authentication

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

## Request

### Headers

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

### Body (application/json)

This endpoint expects an object.

- `items` (list of UpdateScratchFileInputWithPathParams, required)

## Response

### 200

OK

- `items` (list of ScratchFile, required)

## Errors

### 400 Scratch File Batch Update 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 Scratch File Batch Update 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 Scratch File Batch Update 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 Scratch File Batch Update 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 Scratch File Batch Update 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 Scratch File Batch Update 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

### UpdateScratchFileInputWithPathParams

- `id` (string, required)
- `uploadStatus` (enum, required)
  - Allowed values: `SUCCEEDED`

### ScratchFile

A ScratchFile represents raw file content used as intermediate input or output of pipeline steps (see AutomationStepData). Unlike File, ScratchFiles are not surfaced in the Data Catalog because they typically represent transient processing artifacts rather than standalone valuable data. When a ScratchFile is promoted to user-visible status, it is linked to a File object that appears in the Data Catalog. The originAutomationStepData field tracks which pipeline step produced this file. To upload content, create a ScratchFile; it starts with uploadStatus NOT_UPLOADED and returns a presigned uploadUrl. PUT the file's bytes to uploadUrl, then update the ScratchFile with uploadStatus SUCCEEDED to finalize the upload. Finalizing verifies the content was uploaded (up to 5GB) and makes it available via downloadUrl; uploadUrl is only returned until the upload is finalized. If the upload cannot be completed, leave the ScratchFile unfinalized; it remains NOT_UPLOADED. Alternatively, use the create-and-upload method to create and finalize a ScratchFile in one request.

- `__typename` (string, optional)
- `createdAt` (string, optional, nullable)
- `creator` (PrincipalRef, optional)
- `downloadUrl` (string, optional, nullable)
- `errorMessage` (string, optional, nullable)
- `externalFileId` (string, optional, nullable)
- `file` (FileRef, optional, nullable)
- `filename` (string, optional)
- `id` (string, optional)
- `mimeType` (string, optional, nullable)
- `modifiedAt` (string, optional, nullable)
- `name` (string, optional)
- `originAutomationStepData` (AutomationStepDataRef, optional, nullable) — The automation step data that produced this file.
- `size` (integer, optional, nullable)
- `uploadStatus` (enum, optional)
  - Allowed values: `SUCCEEDED`, `FAILED_VALIDATION`, `IN_PROGRESS`, `NOT_UPLOADED`
- `uploadUrl` (string, optional, nullable)
- `originPipelineStepData` (AutomationStepDataRef, optional, nullable, deprecated) — Use originAutomationStepData instead.

### GeneralErrorDetail

### TooManyRequestsErrorBodyDetail

### InternalServerErrorBodyDetail

### PrincipalRef

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

### FileRef

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

### AutomationStepDataRef

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

## Examples

**Request**

```json
{
  "items": [
    {
      "id": "id",
      "uploadStatus": "SUCCEEDED"
    }
  ]
}
```

**Response**

```json
{
  "items": [
    {
      "__typename": "__typename",
      "createdAt": "createdAt",
      "downloadUrl": "downloadUrl",
      "errorMessage": "errorMessage",
      "externalFileId": "externalFileId",
      "filename": "filename",
      "id": "id",
      "mimeType": "mimeType",
      "modifiedAt": "modifiedAt",
      "name": "name",
      "size": 1,
      "uploadStatus": "SUCCEEDED",
      "uploadUrl": "uploadUrl"
    }
  ]
}
```

**SDK Code**

```python
import requests

url = "https://{tenant_name}.benchling.com/api/v3/scratch-file:batch-update"

payload = { "items": [
        {
            "id": "id",
            "uploadStatus": "SUCCEEDED"
        }
    ] }
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.patch(url, json=payload, headers=headers)

print(response.json())
```

```javascript
const url = 'https://{tenant_name}.benchling.com/api/v3/scratch-file:batch-update';
const options = {
  method: 'PATCH',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: '{"items":[{"id":"id","uploadStatus":"SUCCEEDED"}]}'
};

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