Overview

The V3 REST api is designed to provide a more consistent and complete API coverage across all Benchling types in accordance with FAIR principles. The REST API, along with V3 Events and the V3 SDK will be fully powered by the Benchling Domain Graph. This ensures broad coverage and consistency across all developer interfaces.

It also allows us to introduce powerful frameworks across the entire API in the future. Such as, generic Bulk and Upsert support.

The V3 reference docs contain a list of all the endpoints we offer, as well as examples for how to call each of them.

The Python SDK

There is currently no Python SDK for V3. An SDK is planned for a later stage of the V3 rollout.

Early Access Guidelines

Most of the V3 API endpoints are currently v3-alpha stability and subject to change without prior notice, and should not be used for critical production integrations.

Some endpoints are available under v3-beta. This API version only includes endpoints that are considered at minimum beta stability. For these endpoints, we guarantee 30-day notice for any breaking changes introduced to the v3-beta endpoints.

As of Apr 20, 2025 we will also be giving 30 days notice for any API-wide functionality.

📘

Keeping up with breaking changes

We recommend setting up an RSS subscription to our changelog to be alerted about breaking changes: https://docs.benchling.com/changelog.rss

Some developers choose to send notifications to Slack or Teams using RSS integrations (see: Slack RSS app, Teams RSS app)

Feedback

If you have any feedback to share regarding the V3 APIs, please feel free to reach out to [email protected]. We are actively seeking your input!

Tutorial

Setup

You'll first need developer platform access as well as access to the V3 Early Access Program. If you do not have access to the V3 Early Access Program, please reach out to your Benchling CSM to learn about joining.

You can then create a Benchling App to test the new APIs with.

Please note that you must use theV2 Token endpoint with the app credential to retrieve a token when using the API.

Viewing the V3 reference page

To explore the API or test out specific endpoints, you can do so directly from the documentation on your tenant. Given that the V3 API is still in in an early access phase, there is no publicly available documentation page, and the documentation can only be accessed if you have a login and developer platform access.

The documentation is available at {your-domain}.benchling.com/v3-beta/reference/ and {your-domain}.benchling.com/v3-alpha/reference/

Similar to the V2 API docs, you can make calls directly from this documentation page against the data in your tenant.

Calling the API through the documentation produces the same output as calling the API via cURL locally or in your language of choice, and can often be very helpful when trying to debug or understand more about how the API functions.

To make calls, navigate to the endpoint you want to test in the documentation on your tenant. We'll use a benchling demo environment for the following examples, but remember you'll need to visit the domain where you have API access.

List all containers

First, we'll walk you through listing all the containers you have access to in Benchling using the V3 List all containers endpoint. Going to the tenant specific API documentation page, you can search for a specific set of endpoints at the search bar at the top. Then, you can expand a given section to see what endpoints are available.

Clicking the Test API button will enable you to execute requests using the logged in user's API ID via the UI.

There is also a curl command generated that will also execute the same request.

While there is currently no Python SDK, you can still hit these endpoints using Python:

import requests

# Replace with your access token
access_token = "XXXXXXXXX"

url = "https://<YOUR-DOMAIN>.benchling.com/api/v3-alpha/benchling/container/items?sort=modifiedAt%3Adesc"

headers = {
    "Accept": "application/json",
    "Authorization": f"Bearer {access_token}"
}

response = requests.get(url, headers=headers)

# Check for successful response
if response.status_code == 200:
  # Process the JSON response data
  data = response.json()
  print(data)
else:
  print(f"Error: {response.status_code}")
  print(response.text)  # Might contain error details

Create a new container

We also allow creations and updates via the V3 APIs. Currently, not all models are supported although more are being actively added.

Migration guide

There is currently no guide for migrating from V2 to V3 APIs during the early access period but there will be one before general release of the V3 APIs. Please reach out to [email protected] if you have specific scenarios you'd like to see covered in that guide.

What's new?

New endpoints

Some new API endpoints are exclusively available in our V3 REST API, including:

• Collaborators and Policy APIs for permission management
• (Notebook) Entry APIs for creating and updating Notebook content via the API
• Procedures APIs for programmatically interacting with BioProcess / Studies

Rate Limiting

V3 API rate limits are tiered, to reflect the relative cost of operations. Smaller tier numbers mean less requests allowed per interval. Vice versa for larger tier numbers.

Note that the request allocation is approximate, and may be throttled based on existing system load.

"What limit applies to this endpoint?"

From the API reference docs

After expanding the definition for a particular endpoint, scroll down to the bottom to see an OpenAPI extension x-bnch-rate-limit-tier which states the tier for that endpoint.

Typing “limit” in the search bar will filter to show tier rate limit sections that can be expanded to list all endpoints of that tier.

From the OpenAPI spec

Another alternative: viewing the raw OpenAPI specification allows for explicit checking of the tier for each endpoint, via tags/extension:

- description: Tier 1 rate limit endpoints
  name: Tier 1 Rate Limit
- description: Tier 2 rate limit endpoints
  name: Tier 2 Rate Limit
- description: Tier 3 rate limit endpoints
  name: Tier 3 Rate Limit
- description: Tier 4 rate limit endpoints
  name: Tier 4 Rate Limit
- description: Tier 5 rate limit endpoints
  name: Tier 5 Rate Limit

/benchling/aa-sequence/{aa_sequence_id}:
    get:
      description: Get single AaSequence
      operationId: Benchling.AaSequence.Get
      parameters:
      - in: path
        name: aa_sequence_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Benchling.AaSequence'
          description: OK
          headers: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get single AaSequence in Benchling
      tags:
      - Benchling.AaSequence
      - Tier 5 Rate Limit
      x-bnch-rate-limit-tier: 5

"What are the configured limits for my tenant?"

To retrieve configured limits programmatically, searching for “limits” in the search bar on the API docs page should yield an endpoint specifically for retrieving the limits configured for your tenant. The response should match the defaults stated above unless your tenant was approved for a rate limit increase.

Handling rate limits

We recommend the same approach to handling limits as before. Rate limit error response schema below:

If a tiered rate limit is hit, the detail string field of a 429 response will state the corresponding tier number within.

Nested Listing Endpoints

In V3, retrieving a property that is a list of other objects will occur through a nested endpoint with the id of the top-level object as a path parameter. This will allow for clients to receive fully hydrated nested objects and paginate through the list instead of receiving the entire list at once.

For example, listing WellPlate will return a url to fetch the positions:

To get the positions of the WellPlate, clients should call a nested endpoint with the WellPlate id as a path parameter:

This endpoint will return fully hydrated WellPlatePosition objects along with pagination arguments.

Schema specific endpoints

❗️

This feature has been removed from the early access program.

In order to promote the V3 REST APIs to a higher stability more quickly, we are pausing development on this feature. Because parts of it are not yet fully functional, this feature is inaccessible until further notice.

New in the V3 APIs, are the top level endpoints available for each schema in your tenant that you have access to. Given an example custom entity schema Cell Line in the organization stagingtx

with the shape:

schema CellLine {
  cellType: string
  expirationDate: timestamp
  expressedComplex: Complex
  parentCellLine: CellLine
  plasmidPreps: List[PlasmidPrep]
}

We will generate two new listing endpoints, namespaced by the organization the schemas belong to:

https://{domain}.benchling.com/api/v3-alpha/{organization-name}/{schema-name}/items

https://{domain}.benchling.com/api/v3-alpha/{organization-name}/{schema-name}/{item-id}

This is what the example from above looks like in the v3 documentation page:

This endpoint, returns items following the CellLine schema, which hoists the schema fields to be top level fields on the object:

Any schema links to other entities are represented by a TypeReferenceobject which has the shape:

TypeRef {
  __typename: string
  api_id: string
}

FAQ

Can I use V2 and V3 simultaneously?

Yes! Mix and matching APIs is possible. When building an app, it's recommended to use the highest stability version of an endpoint that is available. E.g. if an endpoint is only available in v3-alpha, it may be used alongside v2 endpoints. Similarly, if an endpoint is not yet available in v3-alpha, the most stable version from v2 may be used.

When is SDK support coming?

There is no confirmed release date for a V3 SDK as of right now - if you have use cases that would benefit from one, please reach out to [email protected].

When will V3 events be available?

Very soon!