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

# Working with Attachments

> **Info**
>
> ### Beta APIs
>
> The Document APIs are beta. Send the `EARLY-ACCESS: true` header on every request shown here; without it these endpoints are unavailable. See [Introduction to Documents](/docs/introduction-to-documents) and the [Stability Guidelines](/docs/stability-guidelines).

Documents can reference file attachments anywhere in their content.

## Attaching a file to a document

To attach a file to a document, first upload the file into Benchling as a scratch file.

To upload and attach the file:

1. Create the scratch file that defines an upload location. From the response, retrieve the `uploadUrl` and the `id`. The `uploadUrl` is a presigned S3 URL with a short expiration time. The response includes an expiration header.

   **`Endpoint`**

   ```text title="Endpoint"
   POST /api/v3/scratch-file
   EARLY-ACCESS: true
   ```

   **`Example Request`**

   ```json title="Example Request"
   {"filename": "photo.tif", "name": "Assay Photo"}
   ```

   **`Example Response`**

   ```json title="Example Response"
   {
     "__typename": "ScratchFile",
     "id": "scrfile_lHftrqPCF3WZ",
     "filename": "photo.tif",
     "name": "Assay Photo",
     "uploadStatus": "NOT_UPLOADED",
     "createdAt": "2026-08-14T21:36:50.121387Z",
     "uploadUrl": "<REDACTED>"
   }
   ```

2. Use a client of your choice to upload your file to the presigned URL. S3 expects a `PUT` request to the presigned URL with the binary data of the file in the request body.

3. Finalize the scratch file's `uploadStatus` to indicate that the file has been uploaded to S3.

   **`Endpoint`**

   ```text title="Endpoint"
   PATCH /api/v3/scratch-file/scrfile_lHftrqPCF3WZ
   EARLY-ACCESS: true
   ```

   **`Example Request`**

   ```json title="Example Request"
   {"uploadStatus": "SUCCEEDED"}
   ```

   If your `uploadUrl` expires before you upload, fetch the scratch file again for a new presigned URL.

   **`Endpoint`**

   ```text title="Endpoint"
   GET /api/v3/scratch-file/scrfile_lHftrqPCF3WZ
   EARLY-ACCESS: true
   ```

   **`Example Response`**

   ```json title="Example Response"
   {
     "__typename": "ScratchFile",
     "id": "scrfile_lHftrqPCF3WZ",
     "filename": "photo.tif",
     "name": "Assay Photo",
     "uploadStatus": "NOT_UPLOADED",
     "createdAt": "2026-08-14T21:36:50.121387Z",
     "uploadUrl": "<NEW_REDACTED>"
   }
   ```

4. Insert any scratch file with `uploadStatus: "SUCCEEDED"` into a document using a `partsMutation` such as `insert`.

   **`Endpoint`**

   ```text title="Endpoint"
   PATCH /api/v3/entry/etr_8rVKW0g7
   EARLY-ACCESS: true
   ```

   **`Example Request`**

   ```json title="Example Request"
   {
     "partsMutation": {
       "operationType": "insert",
       "version": "etrver_Ax7b2kR9",
       "position": "end_of_document",
       "parts": [
         {
           "contentType": "attachment",
           "scratchFileId": "scrfile_lHftrqPCF3WZ"
         }
       ]
     }
   }
   ```

## Downloading a file from a document

To download a document attachment, use the `download.url` of its attachment part. Fetch the document's content to retrieve it. The URL is a presigned S3 URL with a short expiration time, given in `download.expiresAt`. If antivirus scanning blocks the file, `download` is `null`; `scanStatus` shows the scan result.

**`Endpoint`**

```text title="Endpoint"
GET /api/v3/entry/etr_2uBIDQGZ9W/parts/items
```

**`Example Response`**

```json title="Example Response"
{
  "items": [
    ...,
    {
      "__typename": "DocumentPartAttachment",
      "id": "docpart_YvkI7VAk9o",
      "modifiedAt": "2026-08-14T22:40:33.573223Z",
      "versionMetadata": { "versionId": "etrver_FDzb3GZY1R", "createdAt": "2026-08-14T22:40:33.573223Z" },
      "externalFileId": "efl_bioqd8S7PU",
      "filename": "results.csv",
      "download": {
        "url": "<REDACTED>",
        "expiresAt": "2026-08-14T22:42:01.757115Z"
      },
      "scanStatus": "NO_THREATS_FOUND"
    },
    ...
  ],
  "nextToken": ""
}
```