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.
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_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.
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.
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:
- First, get the ID of your project using the List Projects endpoint
- 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
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:
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
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
Finally, we’re ready to list DNA sequences. Call the List DNA Sequences endpoint using the registry ID (
$YOUR_REGISTRY_ID) and schema ID (
curl https://$YOUR_DOMAIN/api/v2/dna-sequences?registryId=$YOUR_REGISTRY_ID&schemaId=$YOUR_SCHEMA_ID -u $YOUR_API_KEY:
For more examples of how to use the Benchling API, you can take a look at Benchling's public repository of example integrations.