Skip to navigation

Working with Attachments

Documents can reference file attachments anywhere in their content. This guide covers the scratch file upload flow for attaching a file, and how to download an attachment using its presigned URL.

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

    POST /api/v3/scratch-file
    EARLY-ACCESS: true
  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.

    PATCH /api/v3/scratch-file/scrfile_lHftrqPCF3WZ
    EARLY-ACCESS: true

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

    GET /api/v3/scratch-file/scrfile_lHftrqPCF3WZ
    EARLY-ACCESS: true
  4. Insert any scratch file with uploadStatus: "SUCCEEDED" into a document using a partsMutation such as insert.

    PATCH /api/v3/entry/etr_8rVKW0g7
    EARLY-ACCESS: true

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.

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