Benchling

Welcome to the Benchling API! In this tutorial, we’ll walk you through how to access the API and list the DNA sequences you’ve created in Benchling.

Setup

First, we need to get access to the API.

  • First, please ask your Benchling representative to enable API access
  • Then, generate an API key.
  • For more detailed instructions on how to authenticate to the API, see the Authentication page.

The following examples use $YOUR_DOMAIN and $YOUR_API_KEY to represent variables that you must replace with your own values. For example, if your Benchling instance is example.benchling.com (http://example.benchling.com/) and your API key is sk_12345, an example like

curl $YOUR_DOMAIN -u $YOUR_API_KEY:

needs to be replaced with

curl example.benchling.com -u sk_12345:

before you run the command.

List all DNA sequences

First, we’ll list all DNA sequences that you have access to in Benchling, using the List DNA Sequences endpoint. Don’t forget the colon : at the end - the curl command won’t work without it.

curl https://$YOUR_DOMAIN/api/v2/dna-sequences -u $YOUR_API_KEY:

The endpoint returns a JSON object with an array of DNA Sequence resources in the dnaSequences field. If there are too many sequences to return in a single response, the response will include a nextToken field that can be used to request additional DNA sequences from the API.

List all DNA sequences in a particular project

The List DNA Sequences endpoint has several options for filtering, and one way to filter the results is to only list the DNA sequences in a particular Benchling project. Filtering by project requires multiple steps:

  1. First, get the ID of your project using the List Projects endpoint
  2. Then, pass the project ID to the List DNA Sequences endpoint.

First, call the List Projects endpoint:

curl https://$YOUR_DOMAIN/api/v2/projects -u $YOUR_API_KEY:

The endpoint returns a JSON object with an array of Project resources in the projects field. Each Project resource will have an id field with an identifier like src_muzHDKze.

Then, pass the project ID to the List DNA Sequences endpoint, replacing $YOUR_PROJECT_ID with the ID you got from the List Projects call.

curl https://$YOUR_DOMAIN/api/v2/dna-sequences?projectId=$YOUR_PROJECT_ID -u $YOUR_API_KEY:

List registered DNA sequences

If you are using the Registry application, you can use the Benchling API to list all the DNA sequences in your registry that belong to a particular schema. First, make sure that you’ve configured a schema and created and registered a DNA sequence. Then, to filter for registered DNA sequences of that schema, you can pass in two extra parameters to the List DNA Sequences endpoint:

  • registryId, the ID of your registry in Benchling.
  • schemaId, the ID of your schema.

First, find the ID of your registry using the List Registries endpoint:

curl https://$YOUR_DOMAIN/api/v2/registries -u $YOUR_API_KEY:

The endpoint will return a list of Registry resources, and each Registry resource will have an id field with an identifier like src_gfNcj1gd. If there are multiple registries, you can find the one that’s owned by your organization by looking at the owner field.

Then, find your schema’s ID using the List Entity Schemas endpoint. Run the following command, replacing $YOUR_REGISTRY_ID with the registry ID you obtained from the List Registries endpoint:

curl https://$YOUR_DOMAIN/api/v2/registries/$YOUR_REGISTRY_ID/entity-schemas -u $YOUR_API_KEY:

The endpoint will return a list of EntitySchema resources. To find your schema’s ID, find the schema with the name you are looking for, and then find the id field. The id field will have an identifier like ts_EM122lfJ.

Finally, we’re ready to list DNA sequences. Call the List DNA Sequences endpoint using the registry ID ($YOUR_REGISTRY_ID) and schema ID ($YOUR_SCHEMA_ID):

curl https://$YOUR_DOMAIN/api/v2/dna-sequences?registryId=$YOUR_REGISTRY_ID&schemaId=$YOUR_SCHEMA_ID -u $YOUR_API_KEY:

More examples

For more examples of how to use the Benchling API, you can take a look at Benchling's public repository of example integrations.

Tutorial


Suggested Edits are limited on API Reference Pages

You can only suggest edits to Markdown body content, but not to the API spec.