---
title: "Create and upload a ScratchFile"
method: POST
path: "/api/v3/scratch-file:create-and-upload"
tags: ["Scratch File"]
---

# Create and upload a ScratchFile

`POST /api/v3/scratch-file:create-and-upload`

## Request

- Base URL: `https://{tenant_name}.benchling.com`
- URL: `https://{tenant_name}.benchling.com/api/v3/scratch-file:create-and-upload`
- Auth: HTTP bearer

Create a ScratchFile from either uploaded contents or an existing S3 location. Provide exactly one of `contents` (with a `filename`, up to 10 MiB of UTF-8 sent as an `application/json` body) or `s3Location` (the filename is derived from the location when omitted).

## Request body

- CreateAndUploadScratchFileInput
  - `contents` string
  - `filename` string
  - `s3Location` string

## Response `200`

OK

- 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
  - `createdAt` string, datetime, nullable
  - `creator` PrincipalRef
    - `__typename` string
    - `id` string, api_id
  - `downloadUrl` string, nullable
  - `errorMessage` string, nullable
  - `externalFileId` string, nullable
  - `file` FileRef
    - `__typename` string
    - `id` string, api_id
  - `filename` string
  - `id` string
  - `mimeType` string, nullable
  - `modifiedAt` string, datetime, nullable
  - `name` string
  - `originAutomationStepData` AutomationStepDataRef
    - `__typename` string
    - `id` string, api_id
  - `originPipelineStepData` AutomationStepDataRef
    - `__typename` string
    - `id` string, api_id
  - `size` integer, nullable
  - `uploadStatus` 'SUCCEEDED' | 'FAILED_VALIDATION' | 'IN_PROGRESS' | 'NOT_UPLOADED'
  - `uploadUrl` string, nullable

## Other responses

- `400`: Bad Request
- `403`: Forbidden
- `404`: Not Found
- `409`: Conflict
- `429`: Too Many Requests
- `500`: Internal Server Error

---

[API](https://skmtc.dev/benchling/apis/benchling-api.md) - [All operations](https://skmtc.dev/benchling/apis/benchling-api/llms.txt) - [OpenAPI document](https://skmtc.dev/benchling/apis/benchling-api/revisions/3873a10bf7b8?raw)