Working with Attachments

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.

   EndpointExample RequestExample Response

   POST /api/v3/scratch-file

   {"filename": "photo.tif", "name": "Assay Photo"}

   {
     "__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.

   EndpointExample Request

   PATCH /api/v3/scratch-file/scrfile_lHftrqPCF3WZ

   {"uploadStatus": "SUCCEEDED"}

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

   EndpointExample Response

   GET /api/v3/scratch-file/scrfile_lHftrqPCF3WZ

   {
     "__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.

   EndpointExample Request

   PATCH /api/v3/entry/etr_8rVKW0g7

   {
     "partsMutation": {
       "operationType": "insert",
       "version": "etrver_Ax7b2kR9",
       "coordinates": {
         "position": "end_of_document"
       },
       "parts": [
         {
           "contentType": "attachment",
           "scratchFileId": "scrfile_lHftrqPCF3WZ"
         }
       ]
     }
   }

Downloading a file from a document

To download a document attachment, use the downloadUrl. Fetch the document's content to retrieve it. The downloadUrl is a presigned S3 URL with a short expiration time. The content response includes the expiration time.

GET /api/v3/entry/etr_2uBIDQGZ9W/parts/items

{
  "items": [
    ...,
    {
 "indentation": 0,
      "id": "docpart_OGWsrQDgNV",
      "externalFileId": "efl_nh2fviYpzi",
      "filename": "western-blot.jpg",
      "scanStatus": "NO_THREATS_FOUND",
      "size": 77302,
      "download": {
        "url": "https:/s3.amazonaws.com/benchling-attachments/western-blot.jpg",
        "expiresAt": "2026-09-28T20:13:03.347916Z",
        "__typename": "DocumentAttachmentDownload"
      },
      "customWidth": null,
      "createdAt": "2026-09-28T19:04:54.506586Z",
      "modifiedAt": "2026-09-28T19:04:54.506586Z",
      "versionMetadata": {
        "versionId": "etrver_WUSx9kRxRT",
        "createdAt": "2026-09-28T19:13:40.109785Z",
        "__typename": "DocumentLikeVersionMetadata"
      },
      "modifier": {
        "id": "ent_9FgPmOOo",
        "__typename": "User"
      },
      "__typename": "DocumentPartAttachment"
    },
    ...
  ],
  "nextToken": ""
}