Skip to navigation

Analyses API Developer Guide

The Analyses API lets you build integrations on top of the Benchling Analyses product. This guide covers the import and export workflow, analysis keys, and the API patterns used to exchange data with external systems.

The Analyses API includes a number of endpoints for working with the Benchling Analysis product. Integrators can use the import/export functionality of Benchling analyses to let users interact with external systems, pulling Benchling data out for external analysis and uploading post-analysis data files back in.

This guide walks through how Benchling users interact with the Analyses product, and how apps can extend an analysis through import/export. That includes the Analyses API endpoints in more detail, as well as core concepts such as analysis keys. Like most integrations, we recommend Analysis integrations use app authentication, so before working with the Analyses API make sure you’re familiar with building Benchling Apps.

This page uses V2 because the analysis write path is V2-only

V3 is the recommended API for new development, and it does expose analyses (GET /api/v3/analysis/items, GET /api/v3/analysis/{analysis_id}, GET /api/v3/data-frame/items, and the analysis template endpoints), but all of them are read-only. Patching an analysis and creating a data frame have no V3 equivalent, and the import/export flow below depends on both, so it stays on V2 end to end.

Use the V3 endpoints when you only need to read an analysis, its steps, or its data frames.

Getting started

Before diving in, it’s worth a closer look at how Benchling users create analyses to process their data. Benchling analyses include:

  • Analysis object. Objects that let users view and analyze experimental result data
  • Data frames. Tabular data used in analyses
  • Files. Raw files (images, text, HTML)

Apps interact with analyses through the import/export feature, which lets an integration both export data frames from Benchling and import data frames and files into Benchling. To users, this all happens as part of a single action in their Benchling Analysis.

Analysis integration user flow

Users interact with import/export in the following way. First, a user copies the analysis key from the import/export dialog in Benchling. Next, they provide the key to the integration through an external UI. Finally, the user returns to the Benchling Analysis, where the external system has sent the data frame.

While the purpose of an Analysis integration is to process or analyze data on an external platform, the following components are also crucial:

  • A UI for accepting an analysis key
  • A mechanism for pulling data frames from Benchling
  • A mechanism for pushing data frames and files to Benchling

Analysis key

An analysis key is a value provided to Benchling users when working with the import/export feature. It is composed of the relevant analysis_id and a JSON Web Token (JWT), separated by a colon (:). The analysis_id is the internal Benchling identifier for the analysis, and the JWT can be used to authenticate requests to the customer’s tenant.

Here’s an example key:

ana_ABCD1234:eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c

The JWTs associated with analysis keys expire after 10 minutes, after which users must generate a new one. A new key is generated each time a Benchling user copies one from the import/export dialog, so if you’re using the key to authenticate, be sure to prompt for a new key each time a user runs the external analysis.

While analysis keys include a JWT that can be used to authenticate requests, this is not a best practice. Analysis key authentication is fine for testing, but the 10-minute expiration makes it unsuitable for production applications. Consider creating a Benchling App and using app authentication instead.

The JWT payload portion of an analysis key contains information about the customer’s tenant, including a unique tenant identifier. This matters particularly when building multi-tenant apps. Here’s a Python example of working with analysis keys:

# Separate the analysis_id value from the JWT
analysis_id, key = analysis_key.split(":")
# Split the JWT into its constituent parts
_headers, payload, _signature = key.split(".")
# Decode the JWT payload
jwt_payload = json.loads(base64.b64decode(f"{payload}=="))
tenant = jwt_payload["aud"]

Downloading data frames from Benchling

Users start an analysis by creating an initial data frame from registry data, from a dashboard query, or from existing tabular data. The Benchling Help Center has more on how users interact with the Registry and Insights tools.

This initial data frame is the foundation of the analysis, and the starting point for creating views and importing or exporting other files and data frames. Data frames are the main object analyses work with, and an analysis can work with multiple data frames at once.

A Benchling Analysis showing an initial data frame of tabular assay data
An analysis with an initial data frame

Imports and exports begin with obtaining the relevant inputs. The Get an analysis endpoint (GET /v2-beta/analyses/:analysis_id) returns an analysis object:

{
"id": "ana_DjEC6xL4",
"dataframesIds": [
"dset_t69ysPGQUl4H"
],
"fileIds": [
"file_UoqJSDwI"
],
"folderId": "lib_Gfjd3i1m"
}

Note that there may be multiple data frames and files returned, since each analysis can have any number of them to download.

Data frame inputs

With a data frame ID from the dataframesIds array, query the Get a data frame endpoint (GET /v2/data-frames/:dataframes_id) for the data frame’s metadata. Two fields matter most:

  • uploadStatus: the current status of the data frame, one of IN_PROGRESS, SUCCEEDED, FAILED_VALIDATION, or NOT_UPLOADED. For the purposes of getting an initial data frame, we’re only concerned with SUCCEEDED.
  • manifest: a list of the files that make up the data frame, each represented by an object including the name and URL. The value of the url field varies with the data frame’s uploadStatus:
    • For SUCCEEDED data frames, it is the file’s download URL.
    • For NOT_UPLOADED data frames, it is a pre-signed URL used to upload a file via the Update a data frame endpoint (PATCH /v2-beta/data-frames/{dataframes_id}).
    • For all other statuses, url is null.

For data frames with an uploadStatus of SUCCEEDED, the url fields are pre-signed URLs that can be used to download the data frame CSV data. Here’s an example data frame:

sample,ct,ct_mean,quantity,quantity_mean
qPCR Sample 15,17.453,17.419,0.245,0.251
qPCR Sample 14,17.364,17.257,0.26,0.28
qPCR Sample 13,16.481,16.43,0.469,0.486
qPCR Sample 12,30.507,30.345,0.01,0.011
qPCR Sample 11,30.072,30.345,0.01,0.011
qPCR Sample 10,30.456,30.345,0.01,0.011
qPCR Sample 9,22.175,22.144,0.01,0.011
qPCR Sample 8,22.106,22.144,0.011,0.011
qPCR Sample 7,22.152,22.144,0.011,0.011
qPCR Sample 6,17.316,17.306,0.269,0.271
qPCR Sample 1,11.115,11.142,16.858,16.568

File inputs

Like data frame inputs, use the file IDs from the fileIds array to query the Get a file endpoint (GET /v2/files/{file_id}) for metadata about the file:

{
"errorMessage": null,
"uploadStatus": "SUCCEEDED",
"id": "file_Of5GuBSq",
"name": "IC50Chart",
"filename": "IC50Chart.png",
"folderId": "lib_Gfjd3i1m"
}

Unlike data frame inputs, the response doesn’t contain a manifest field. Instead, a Content-Location header includes the pre-signed URL where the file can be downloaded.

Uploading data frames and files to a Benchling Analysis

Once an integration has completed an external analysis, the final product is uploaded back to the Benchling Analysis. Both data frames (for tabular data) and files (for images or other file types) can be pushed back.

Pushing data back involves creating the data frame or file definition in Benchling, then uploading the relevant data to it.

Files must live in a folder

Files are first-class objects in Benchling, and therefore require a location when they are created, which is what the required folderId parameter supplies. Usually, files are created in the same folder as the associated analysis. The Folders API has more on folders in Benchling.

Importing new data frames to a Benchling Analysis

Create data frames using the Create a data frame endpoint (POST /v2/data-frames), first specifying the data frame’s manifest, including the name of the data frame or the file to be uploaded:

{
"manifest": [
{
"fileName": "09-14-2022_011620_PM_well_plate-part-00000.csv"
}
],
"name": "09-14-2022 01:16:20 PM well plate"
}

The response includes a complete data frame object with a status of NOT_UPLOADED; the manifest now includes a pre-signed URL, and the object has a data frame ID:

{
"errorMessage": null,
"id": "dset_LlDFupKyErxx",
"manifest": [
{
"fileName": "09-14-2022_011620_PM_well_plate-part-00000.csv",
"url": "https://benchling-location.s3.amazonaws.com/deploys/location/data_frames/source_files/.../09-14-2022_011620_PM_well_plate-part-00000.csv?..."
}
],
"name": "09-14-2022 01:16:20 PM well plate",
"uploadStatus": "NOT_UPLOADED"
}

Using the url, upload the CSV to Benchling. Include the x-amz-server-side-encryption: AES256 header to work with Benchling’s server-side encryption:

curl -H "x-amz-server-side-encryption: AES256" -X PUT -T <LOCAL_FILE> -L <S3_PUT_URL>

Finally, update the status of the data frame to IN_PROGRESS using the data frame ID and the Update a data frame endpoint (PATCH /v2/data-frames/{dataframes_id}):

{
"uploadStatus": "IN_PROGRESS"
}

This endpoint is asynchronous; a successful request returns a 202 Accepted with an empty response body and launches the process to validate and transform the uploaded CSV into a data frame. Once complete, the data frame’s status is automatically updated to SUCCEEDED or FAILED_VALIDATION.

Importing new files to a Benchling Analysis

File imports follow a nearly identical process, with a couple of differences. First, create a file definition in Benchling using the Create a file endpoint (POST /v2/files):

{
"name": "IC50Chart",
"filename": "IC50Chart.png",
"folderId": "lib_Gfjd3i1m"
}

This creates the file definition, and as with data frames a file ID and pre-signed URL are returned:

{
"errorMessage": null,
"id": "file_Of5GuBSq",
"name": "IC50Chart",
"filename": "IC50Chart.png",
"folderId": "lib_Gfjd3i1m",
"uploadStatus": "NOT_UPLOADED"
}

Notably, the upload URL is not included in the response body. It is in the Content-Location header instead. Upload the file to that URL, again including the x-amz-server-side-encryption: AES256 header:

curl -H "x-amz-server-side-encryption: AES256" -X PUT -T <LOCAL_FILE> -L <S3_PUT_URL>

Finally, update the status of the file definition. Unlike data frames, files undergo no validation or conversion, so the status can be set directly to SUCCEEDED:

{
"uploadStatus": "SUCCEEDED",
"folderId": "lib_Gfjd3i1m"
}

Benchling supports a maximum file size of 30 MB. Currently supported file types are .html, .jmp, .jrn, .jrp, .jpeg, .jpg, .png, .csv, and .txt.

End-to-end example

Here is the file and data frame upload process in Python:

import json
import os
import requests
# Calls should be authenticated using the app's OAuth access token
token = os.environ["TOKEN"]
tenant = "my.benchling.com"
# For file uploads:
filename = "myfile.txt"
name = "My File"
# Create the file definition in Benchling
file_post = requests.post(
f"https://{tenant}/api/v2/files",
data=json.dumps({"filename": filename, "folderId": "lib_lOAKZhDQ", "name": name}),
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)
# Store the upload URL and file_id
file_post_resp = json.loads(file_post.content)
bench_put_url = file_post.headers["Content-Location"]
file_id = file_post_resp["id"]
# Upload the file contents to Benchling
bench_put = requests.put(
bench_put_url,
data=open(filename, "rb"),
headers={"x-amz-server-side-encryption": "AES256"},
)
# Update the file object in Benchling to indicate success
file_patch = requests.patch(
f"https://{tenant}/api/v2/files/{file_id}",
data=json.dumps({"uploadStatus": "SUCCEEDED"}),
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)
# For data frame uploads:
filename = "mydataframe.csv"
dataframe_name = "My Data Frame"
# Create the data frame definition in Benchling
dataframe_post = requests.post(
f"https://{tenant}/api/v2/data-frames",
data=json.dumps({"manifest": [{"fileName": filename}], "name": dataframe_name}),
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)
# Store the upload URL and dataframe_id
dataframe_post_resp = json.loads(dataframe_post.content)
bench_put_url = dataframe_post_resp["manifest"][0]["url"]
dataframe_id = dataframe_post_resp["id"]
# Upload the data frame file to Benchling
bench_put = requests.put(
bench_put_url,
data=open(filename, "rb"),
headers={"x-amz-server-side-encryption": "AES256"},
)
# Update the data frame object in Benchling to begin processing
dataframe_patch = requests.patch(
f"https://{tenant}/api/v2/data-frames/{dataframe_id}",
data=json.dumps({"uploadStatus": "IN_PROGRESS"}),
headers={"Authorization": f"Bearer {token}", "Content-Type": "application/json"},
)

Associating data frames and files to an analysis

Once data frames or files from an external analysis have been uploaded to Benchling, they can be attached to the analysis. This means updating the analysis to include them using the Update an analysis endpoint (PATCH /v2-beta/analyses/{analysis_id}). Additional requests with data frames or files append the new objects to the analysis.

Attaching a data frame:

{
"dataframesIds": [
"dset_LlDFupKyErxx"
]
}

The same request in Python:

patch_data = requests.patch(
f"https://{tenant}/api/v2-beta/analyses/{analysis_id}",
data=json.dumps({"outputData": {"dataframesIds": ["dset_LlDFupKyErxx"]}}),
headers={"Authorization": f"Bearer {token}"},
)