Skip to navigation
Start Here

Overview

The Benchling Developer Platform lets you programmatically access and edit data in Benchling. This page maps the platform's tools to the four things people most often build with them.

The platform is most commonly used for:

  • Keeping Benchling in sync with other systems
  • Bulk loading and exporting data
  • Creating dashboards and charts of Benchling data
  • Integrating with instruments in the lab

These activities are accomplished through several different developer tools and interfaces, as pictured in the high-level architecture diagram below:

Architecture diagram of the Benchling Developer Platform, showing the REST API, events, warehouse, and Benchling Apps around a central Benchling tenant
The Benchling Developer Platform at a high level

Each of the top use cases can be accomplished through a variety of these tools, and our recommended methods are broken out in the use cases below, along with links to dive deeper into each system. You can also jump to Key Links to see everything the developer platform has to offer. If you’re building a workflow that reacts to Benchling changes, start with the REST API Reference.

Accessing the Developer Platform

Each user who needs the Developer Platform must have its access set to “Full” in the Capability Management tool. To do this, you must be a Tenant Admin: open the Tenant Admin Console and go to the “Users” tab.

Tenant Admin Console showing the Users tab
The Users tab of the Tenant Admin Console
Capability Management panel with Developer Platform access set to Full
Setting Developer Platform access to Full

After getting access, generate your personal user API key on your user settings page. It also gives you access to the interactive API reference documentation. The “Setup” section of Getting Started with the API shows where to find it.

For more on setting up the Developer Platform capability, see the help article on accessing the Benchling Developer Platform.

Keeping Benchling in sync with other systems

When integrating Benchling with another system, you typically want a Benchling App and the REST API:

Architecture diagram showing a Benchling App mediating between Benchling and an external system over the REST API
A sync integration built on a Benchling App and the REST API

This is primarily because:

  • You likely need to both read and write data.
  • You likely need the data guaranteed latest, and cannot wait for changes to sync to the warehouse.
  • You likely need to limit how much data the integration can access.

Getting Started with Benchling Apps covers how to build this type of app. We highly recommend the Python SDK if you’re comfortable in Python.

Advanced: evented apps

To reduce how much polling your app needs to do, or to build a feature that triggers off actions in Benchling, use Benchling’s event delivery system alongside the REST API. Most integrations should start with the REST API Reference and Getting Started with Webhooks, while Getting Started with EventBridge covers the EventBridge path for architectures that depend on AWS-native routing. The Request and Slack integration walkthrough is a worked example of an evented app.

Advanced: authenticating as any user

If Benchling users interact directly with another system, you might want the changes they make there reflected in Benchling’s audit and activity systems, or want to leverage Benchling’s permissioning system. Making calls as any user in Benchling, not just one as through their API key, requires setting up OIDC authentication between Benchling and your IDP, described in the OIDC section of the Authentication guide. Note that the Python SDK does not currently support OIDC authentication.

Bulk loading and exporting data

Bulk loading and exporting through developer interfaces comes down to needing the control that code provides. Benchling’s developer interfaces offer several methods for data ingest and egress; this section gives high-level guidelines rather than an exhaustive list.

Data ingest

The REST API is the only developer interface that supports writing data into Benchling. Even so, your solution could take several forms.

For a script intended to run once, or to be run directly by a user, a user API key is the simplest way to make the calls, and their actions will be accurately represented in Benchling’s audit and activity logs. Getting Started with the API covers the setup, and the REST API Reference shows what kinds of data you can write.

For a persistent or long-running application that regularly uploads data, create a Benchling App so the integration isn’t tied to a single user. See Getting Started with Benchling Apps.

Either way, we highly recommend the Python SDK if you’re comfortable in Python, as it supports both methods.

Once you’ve completed the getting started guides, the results upload guide walks through a richer example of writing data through the API.

Data export

Exporting data is also generally best accomplished through the REST API, again using a user API key for one-off scripts and Benchling Apps for more persistent use cases, with the Python SDK if you’re comfortable in Python.

If you’re more comfortable in SQL or need very large amounts of data, and the data doesn’t need to be live up to the minute, you can also use the Benchling Data Warehouse. Getting Started with the Warehouse covers how to get access.

Creating dashboards and charts of Benchling data

Benchling can visualize data natively in Insights, and also supports other analytics tools through the warehouse connection. The Benchling Data Warehouse provides a SQL database connection that can be queried in a variety of ways. Common third-party visualization tools can connect directly and query your data out of the box, or you can connect from a Jupyter notebook and tools like it. Getting Started with the Warehouse has more on getting set up.

Without access to the Benchling Data Warehouse, you can still query your data through the REST API using your user API key. The API is equally accessible from environments like Jupyter, and especially easy with the Python SDK. If you’re not using Python, you can make calls directly in your language of choice. Getting Started with the API covers the basics.

Writing back analysis results

Whichever method you use to query the data, writing it back to Benchling is only possible through the REST API. The results upload guide is a worked example.

Integrating with instruments in the lab

Instruments are a key part of any lab ecosystem. To automate workflows or data collection, you can use the developer platform to connect Benchling to your instruments. We generally recommend a Benchling App to represent the instrument within Benchling:

Architecture diagram showing a lab instrument writing data into Benchling through a Benchling App
A Benchling App representing a lab instrument

You can then permission the app to write data to the appropriate places and track its activity independently. Getting Started with Benchling Apps covers how to set the app up, and the results upload guide covers uploading the results to Benchling.

To integrate the instrument with the Notebook, capturing input from a user or surfacing results in the Notebook UI, you’ll need Benchling Connect. The lab automation guide walks through getting instrument files uploaded and processed in the Notebook.