openapi: 3.0.1
info:
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: Benchling AA Sequences DNA Sequences API
version: 2.0.0
description: 'AA Sequences are the working units of cells that make everything run (they help make structures, catalyze reactions and allow for signaling - a kind of internal cell communication). On Benchling, these are comprised of a string of amino acids and collections of other attributes, such as annotations.
'
servers:
- url: /api/v2
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'DNA sequences are the bread and butter of the Benchling Molecular Biology suite. On Benchling, these are comprised of a string of nucleotides and collections of other attributes, such as annotations and primers.
'
name: DNA Sequences
paths:
/dna-sequences:
get:
description: List DNA sequences
operationId: listDNASequences
parameters:
- description: 'Number of results to return. Defaults to 50, maximum of 100.
'
in: query
name: pageSize
schema:
default: 50
maximum: 100
minimum: 0
nullable: false
type: integer
- description: Token for pagination
in: query
name: nextToken
schema:
type: string
- in: query
name: sort
schema:
default: modifiedAt:desc
description: 'Method by which to order search results. Valid sorts are name, modifiedAt, and createdAt. Optionally add :asc or :desc to specify ascending or descending order. Default is modifiedAt.
'
enum:
- createdAt
- createdAt:asc
- createdAt:desc
- modifiedAt
- modifiedAt:asc
- modifiedAt:desc
- name
- name:asc
- name:desc
nullable: false
type: string
- description: 'Datetime, in RFC 3339 format. Supports the > and < operators. Time zone defaults to UTC. Restricts results to those created in the specified range. e.g. > 2017-04-30. Date ranges can be specified with the following nomenclature > YYYY-MM-DD AND <YYYY-MM-DD.
'
examples:
and-range:
summary: Filter for all models created within a certain range using the AND operator.
value: '> 2022-03-01 AND < 2022-04-01'
full-rfc-3339-format:
summary: Filter for created models using the full RFC 3339 format
value: '> 2020-12-31T21:07:14-05:00'
greater-than-example:
summary: Filter for all models created after a certain date
value: '> 2022-03-01'
in: query
name: createdAt
schema:
type: string
- description: 'Datetime, in RFC 3339 format. Supports the > and < operators. Time zone defaults to UTC. Restricts results to those modified in the specified range. e.g. > 2017-04-30. Date ranges can be specified with the following nomenclature > YYYY-MM-DD AND <YYYY-MM-DD.
'
examples:
and-range:
summary: Filter for all models modified within a certain range using the AND operator.
value: '> 2022-03-01 AND < 2022-04-01'
full-rfc-3339-format:
summary: Filter for modified models using the full RFC 3339 format
value: '> 2020-12-31T21:07:14-05:00'
greater-than-example:
summary: Filter for all models modified after a certain date
value: '> 2022-03-01'
in: query
name: modifiedAt
schema:
type: string
- description: Name of a DNA Sequence. Restricts results to those with the specified name, alias, or entity registry ID.
in: query
name: name
schema:
type: string
- description: Name substring of a DNA Sequence. Restricts results to those with names, aliases, or entity registry IDs that include the provided substring.
in: query
name: nameIncludes
schema:
type: string
- description: Full bases of the DNA sequence. Restricts results to those with the specified bases, case-insensitive, allowing for circular or reverse complement matches. Does not allow partial matching or loose matching via degenerate bases.
in: query
name: bases
schema:
type: string
- description: ID of a folder. Restricts results to those in the folder.
in: query
name: folderId
schema:
type: string
- description: 'Comma-separated list of entry IDs. Restricts results to DNA sequences mentioned in those entries.
'
in: query
name: mentionedIn
schema:
type: string
- description: ID of a project. Restricts results to those in the project.
in: query
name: projectId
schema:
type: string
- description: 'ID of a registry. Restricts results to those registered in this registry. Specifying "null" returns unregistered items.
'
in: query
name: registryId
schema:
nullable: true
type: string
- description: 'ID of a schema. Restricts results to those of the specified schema.
'
in: query
name: schemaId
schema:
type: string
- description: 'Filter based on schema field value (not display value). Restricts results to those with a field whose value matches the filter. For Integer, Float, and Date type fields, supports the >= and <= operators (but not < or >). If any schemaField filters are present, the schemaId param must also be present. Note that all operators must be separated from any values by a single space.
'
in: query
name: schemaFields
schema:
$ref: '#/components/schemas/SchemaFieldsQueryParam'
- description: 'Archive reason. Restricts items to those with the specified archive reason. Use "NOT_ARCHIVED" to filter for unarchived DNA sequences. Use "ANY_ARCHIVED" to filter for archived DNA sequences regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived.
'
examples:
1_not_archived:
summary: Only include unarchived items (default).
value: NOT_ARCHIVED
2_archived_reason:
summary: Includes items archived for a specific reason.
value: Retired
3_any_archived:
summary: Includes items archived for any reason.
value: ANY_ARCHIVED
4_any_archived_or_not_archived:
summary: Includes both archived and unarchived items.
value: ANY_ARCHIVED_OR_NOT_ARCHIVED
in: query
name: archiveReason
schema:
type: string
- description: 'Comma-separated list of item IDs. Restricts results to those that mention the given items in the description.
'
in: query
name: mentions
schema:
type: string
- description: 'Comma-separated list of ids. Matches all of the provided IDs, or returns a 400 error that includes a list of which IDs are invalid.
'
in: query
name: ids
schema:
example: seq_VfVOART1,seq_RFhDGaaC
type: string
- description: 'Comma-separated list of entity registry IDs. Maximum of 100. Restricts results to those that match any of the specified registry IDs.
'
in: query
name: entityRegistryIds.anyOf
schema:
example: TP001,TP002
type: string
- description: 'Comma-separated list of names. Maximum of 100. Restricts results to those that match any of the specified names, aliases, or entity registry IDs, case insensitive. Warning - this filter can be non-performant due to case insensitivity.
'
in: query
name: names.anyOf
schema:
example: MyName1,MyName2
type: string
- description: 'Comma-separated list of names. Maximum of 100. Restricts results to those that match any of the specified names, aliases, or entity registry IDs, case sensitive.
'
in: query
name: names.anyOf.caseSensitive
schema:
example: MyName1,MyName2
type: string
- description: Comma separated list of users IDs
in: query
name: creatorIds
schema:
example: ent_a0SApq3z
type: string
- description: Comma separated list of user or app IDs. Maximum of 100.
in: query
name: authorIds.anyOf
schema:
example: ent_a0SApq3z,ent_b4AApz9b
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
**Note**: Fields annotations, translations, and primers cannot be introspected with the returning parameter, and any sub fields will be ignored. E.g.: "dnaSequences.annotations.id" will return the same as "dnaSequences.annotations".
'
in: query
name: returning
schema:
example: dnaSequences.id, dnaSequences.modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesPaginatedList'
description: OK
headers:
Result-Count:
description: The total number of items that match the given query
schema:
type: integer
x-rate-limit-limit:
description: The number of allowed requests in the current rate-limit period
schema:
type: integer
x-rate-limit-remaining:
description: The number of requests remaining in the current rate-limit period
schema:
type: integer
x-rate-limit-reset:
description: The number of seconds remaining in the current rate-limit period
schema:
type: integer
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: List DNA sequences
tags:
- DNA Sequences
post:
description: Create a DNA sequence
operationId: createDNASequence
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequenceCreate'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequence'
description: Created
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
'503':
description: Deprecated, a 429 is returned for too many requests
summary: Create a DNA sequence
tags:
- DNA Sequences
/dna-sequences/{dna_sequence_id}:
get:
description: Get a DNA sequence
operationId: getDNASequence
parameters:
- in: path
name: dna_sequence_id
required: true
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
**Note**: Fields annotations, translations, and primers cannot be introspected with the returning parameter, and any sub fields will be ignored. E.g.: "annotations.id" will return the same as "annotations".
'
in: query
name: returning
schema:
example: id,modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequence'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Get a DNA sequence
tags:
- DNA Sequences
patch:
description: Update a DNA sequence
operationId: updateDNASequence
parameters:
- in: path
name: dna_sequence_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequenceUpdate'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequence'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Update a DNA sequence
tags:
- DNA Sequences
/dna-sequences/{entity_registry_id}:upsert:
patch:
description: 'Create or update a registered DNA sequence.
Schema field links can be populated using entity registry IDs or API IDs. In the `value` field of the [Field](#/components/schemas/FieldWithResolution) resource, the object `{"entityRegistryId": ENTITY_REGISTRY_ID}` may be provided instead of the API ID if desired (see example value).
'
operationId: upsertDNASequence
parameters:
- in: path
name: entity_registry_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequenceUpsertRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequence'
description: OK
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequence'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Create or update a registered DNA sequence
tags:
- DNA Sequences
/dna-sequences:archive:
post:
description: Archive DNA sequences
operationId: archiveDNASequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesArchive'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesArchivalChange'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Archive DNA sequences
tags:
- DNA Sequences
/dna-sequences:auto-annotate:
post:
description: Auto-annotate DNA sequences with matching features from specified Feature Libraries. Limit of 2000 DNA Sequences per request.
operationId: autoAnnotateDnaSequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutoAnnotateDnaSequences'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
When successful, the task has an empty response.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Auto-annotate DNA sequences with matching features from specified Feature Libraries
tags:
- DNA Sequences
/dna-sequences:autofill-parts:
post:
description: Autofill DNA sequence parts. Limit of 2000 DNA Sequences per request.
operationId: autofillDNASequenceParts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutofillSequences'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
When successful, the task has an empty response.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Autofill DNA sequence parts
tags:
- DNA Sequences
/dna-sequences:autofill-transcriptions:
post:
description: Autofill DNA sequence transcriptions from RNA Sequences with matching schemas and bases. Limit of 2000 DNA Sequences per request.
operationId: autofillDNASequenceTranscriptions
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutofillSequences'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
When successful, the task has an empty response.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Autofill DNA sequence transcriptions
tags:
- DNA Sequences
/dna-sequences:autofill-translations:
post:
description: Autofill DNA sequence translations. Limit of 2000 DNA Sequences per request.
operationId: autofillDNASequenceTranslations
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutofillSequences'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
When successful, the task has an empty response.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Autofill DNA sequence translations
tags:
- DNA Sequences
/dna-sequences:bulk-create:
post:
description: Bulk Create DNA sequences. Limit of 1000 DNA Sequences per request.
operationId: bulkCreateDNASequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesBulkCreateRequest'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
When successful, the task returns a full list of [DNA Sequence](#/DNA%20Sequences/getDNASequence) resources that were created.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Bulk Create DNA sequences
tags:
- DNA Sequences
/dna-sequences:bulk-get:
get:
description: Bulk get DNA sequences by ID
operationId: bulkGetDNASequences
parameters:
- description: 'Comma-separated list of IDs of DNA sequences to get.
'
in: query
name: dnaSequenceIds
required: true
schema:
type: string
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
**Note**: Fields annotations, translations, and primers cannot be introspected with the returning parameter, and any sub fields will be ignored. E.g.: "dnaSequences.annotations.id" will return the same as "dnaSequences.annotations".
'
in: query
name: returning
schema:
example: dnaSequences.id,dnaSequences.modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesBulkGet'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Bulk get DNA sequences by ID
tags:
- DNA Sequences
/dna-sequences:bulk-update:
post:
description: Bulk Update DNA sequences. Limit of 1000 DNA Sequences per request.
operationId: bulkUpdateDNASequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesBulkUpdateRequest'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
When successful, the task returns a full list of [DNA Sequence](#/DNA%20Sequences/getDNASequence) resources that were updated.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Bulk Update DNA sequences
tags:
- DNA Sequences
/dna-sequences:bulk-upsert:
post:
description: 'All entities and their schemas must be within the same registry.
This operation performs the following actions:
1. Any existing objects are looked up in Benchling by the provided entity registry ID.
2. Then, all objects are either created or updated accordingly, temporarily skipping any schema field links between objects.
3. Schema field links can be populated using entity registry IDs or API IDs. In the `value` field of the [Field](#/components/schemas/FieldWithResolution) resource, the object `{"entityRegistryId": ENTITY_REGISTRY_ID}` may be provided instead of the API ID if desired (see example value). You may link to objects being created in the same operation.
4. Entities are registered, using the provided name and entity registry ID.
If any action fails, the whole operation is canceled and no objects are created or updated.
Limit of 1000 DNA Sequences per request.
'
operationId: bulkUpsertDnaSequences
parameters:
- description: 'Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, ''*''. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
'
in: query
name: returning
schema:
example: dnaSequences.id,dnaSequences.creator.handle
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesBulkUpsertRequest'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
When successful, the task returns the resources of the objects that were upserted.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Bulk upsert DNA sequences
tags:
- DNA Sequences
/dna-sequences:find-matching-regions:
post:
description: Find matching regions for DNA sequences. Limit of 1000 DNA Sequences per request.
operationId: findMatchingRegionsDnaSequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesFindMatchingRegion'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
It is used to search for DNA sequences that are either subsequences or exact matches of the provided target sequences.
Each returned item represents the group of sequences that partially or fully match the target sequence."
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Find matching regions for DNA sequences
tags:
- DNA Sequences
/dna-sequences:match-bases:
post:
description: 'Returns DNA Sequences that exactly match the provided bases.
'
operationId: matchBasesDnaSequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MatchBasesRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesPaginatedList'
description: A filtered list of DNA Sequences
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: List entities with matching bases
tags:
- DNA Sequences
/dna-sequences:optimize-codons:
post:
description: Create codon-optimized DNA sequences.
operationId: optimizeCodons
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/OptimizeCodons'
responses:
'202':
content:
application/json:
schema:
$ref: '#/components/schemas/AsyncTaskLink'
description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.
When successful, the task has an empty response.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Create codon-optimized DNA sequences.
tags:
- DNA Sequences
/dna-sequences:search-bases:
post:
description: 'Returns DNA Sequences that contain the provided bases. Search indexing is asynchronous, so results my be not be available immediately after creation.
'
operationId: searchDnaSequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchBasesRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesPaginatedList'
description: A filtered list of DNA Sequences
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Search DNA Sequences
tags:
- DNA Sequences
/dna-sequences:unarchive:
post:
description: Unarchive DNA sequences
operationId: unarchiveDNASequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesUnarchive'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/DnaSequencesArchivalChange'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Unarchive DNA sequences
tags:
- DNA Sequences
components:
schemas:
DnaSequencesFindMatchingRegion:
additionalProperties: false
properties:
registryId:
description: An optional Registry ID to restrict the region search to
example: src_ae40j3TZ
type: string
schemaId:
description: API ID for an Entity Schema. Restricts results to DNA Sequences of this schema type.
example: ts_n4l12nf0
type: string
targetDnaSequenceIds:
description: API IDs of the DNA sequences which matching regions will be found for
example:
- seq_W7KgYydE
- seq_g7SI2nih
items:
type: string
maxItems: 1000
type: array
required:
- targetDnaSequenceIds
- schemaId
type: object
DnaSequenceUpsertRequest:
allOf:
- $ref: '#/components/schemas/EntityUpsertBaseRequest'
- $ref: '#/components/schemas/DnaSequenceBaseRequestForCreate'
- required:
- annotations
- primers
Primer:
properties:
bases:
readOnly: true
type: string
bindPosition:
readOnly: true
type: integer
color:
readOnly: true
type: string
end:
description: 0-based exclusive end index. The end of the sequence is always represented as 0.
type: integer
name:
readOnly: true
type: string
oligoId:
type: string
overhangLength:
readOnly: true
type: integer
start:
description: 0-based inclusive start index.
type: integer
strand:
example: 1
type: integer
type: object
DnaSequencesArchivalChange:
description: 'IDs of all items that were archived or unarchived, grouped by resource type. This includes the IDs of DNA sequences along with any IDs of batches that were archived / unarchived.
'
properties:
batchIds:
items:
type: string
type: array
dnaSequenceIds:
items:
type: string
type: array
type: object
Fields:
additionalProperties:
$ref: '#/components/schemas/Field'
type: object
DnaSequenceBaseRequestForCreate:
additionalProperties: false
allOf:
- $ref: '#/components/schemas/DnaSequenceBaseRequest'
- required:
- bases
- isCircular
- name
FieldWithResolution:
allOf:
- $ref: '#/components/schemas/Field'
- properties:
value:
allOf:
- $ref: '#/component
# --- truncated at 32 KB (59 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-dna-sequences-api-openapi.yml