openapi: 3.0.1
info:
license:
name: Apache 2.0
url: http://www.apache.org/licenses/LICENSE-2.0.html
title: Benchling AA Sequences RNA 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: Chains of linear, single stranded RNA that support most capabilities and attributes of DNA Sequences.
name: RNA Sequences
paths:
/rna-sequences:
get:
description: List RNA sequences
operationId: listRNASequences
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
- 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.
'
in: query
name: sort
schema:
default: modifiedAt:desc
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 an RNA 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 an RNA 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 RNA 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 RNA 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 RNA sequences. Use "ANY_ARCHIVED" to filter for archived RNA 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_VzVOART1,seq_RahDGaaC
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: ID of the notation to use in populating the customNotation field.
in: query
name: customNotationId
schema:
example: sntx_lRe007yZ
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.: "rnaSequences.annotations.id" will return the same as "rnaSequences.annotations".
'
in: query
name: returning
schema:
example: rnaSequences.id, rnaSequences.modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequencesPaginatedList'
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 RNA sequences
tags:
- RNA Sequences
post:
description: Create an RNA sequence
operationId: createRNASequence
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequenceCreate'
responses:
'201':
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequence'
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 an RNA sequence
tags:
- RNA Sequences
/rna-sequences/{rna_sequence_id}:
get:
description: Get an RNA sequence
operationId: getRNASequence
parameters:
- in: path
name: rna_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
- description: ID of the notation to use in populating the customNotation field.
in: query
name: customNotationId
schema:
example: sntx_lRe007yZ
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequence'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Get an RNA sequence
tags:
- RNA Sequences
patch:
description: Update an RNA sequence
operationId: updateRNASequence
parameters:
- in: path
name: rna_sequence_id
required: true
schema:
type: string
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequenceUpdate'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequence'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Update an RNA sequence
tags:
- RNA Sequences
/rna-sequences:archive:
post:
description: Archive RNA Sequences. RNA sequences that are already registered will not be removed from the registry.
operationId: archiveRNASequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequencesArchive'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequencesArchivalChange'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Archive RNA Sequences
tags:
- RNA Sequences
/rna-sequences:auto-annotate:
post:
description: Auto-annotate RNA sequences with matching features from specified Feature Libraries. U/T bases are treated as interchangeable in both features and sequences.
operationId: autoAnnotateRnaSequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutoAnnotateRnaSequences'
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 RNA sequences with matching features from specified Feature Libraries
tags:
- RNA Sequences
/rna-sequences:autofill-parts:
post:
description: Autofill parts from matching RNA Sequences with linked schemas.
operationId: autofillRNASequenceParts
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutofillRnaSequences'
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 RNA sequence parts
tags:
- RNA Sequences
/rna-sequences:autofill-translations:
post:
description: Autofill RNA sequence translations
operationId: autofillRNASequenceTranslations
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/AutofillRnaSequences'
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 RNA sequence translations from Amino Acid sequences with matching schemas
tags:
- RNA Sequences
/rna-sequences:bulk-create:
post:
description: Bulk Create RNA sequences. Limit of 1000 RNA Sequences per request.
operationId: bulkCreateRNASequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequencesBulkCreateRequest'
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 [RNA Sequence](#/RNA%20Sequences/bulkGetRNASequences) resources that were created.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Bulk Create RNA sequences
tags:
- RNA Sequences
/rna-sequences:bulk-get:
get:
description: Bulk get RNA sequences by ID
operationId: bulkGetRNASequences
parameters:
- description: 'Comma-separated list of IDs of RNA sequences to get.
'
in: query
name: rnaSequenceIds
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.: "rnaSequences.annotations.id" will return the same as "rnaSequences.annotations".
'
in: query
name: returning
schema:
example: rnaSequences.id, rnaSequences.modifiedAt
type: string
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequencesBulkGet'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Bulk get RNA sequences by ID
tags:
- RNA Sequences
/rna-sequences:bulk-update:
post:
description: Bulk Update RNA sequences
operationId: bulkUpdateRNASequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequencesBulkUpdateRequest'
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 [RNA Sequences](#/RNA%20Sequences/bulkGetRNASequences) resources that were updated.
'
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Bulk Update RNA sequences
tags:
- RNA Sequences
/rna-sequences:match-bases:
post:
description: Return RNA sequences whose bases exactly match the provided query.
operationId: matchBasesRnaSequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/MatchBasesRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequencesPaginatedList'
description: A filtered list of RNA Sequences
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Match RNA sequences by bases
tags:
- RNA Sequences
/rna-sequences:search-bases:
post:
description: 'Returns RNA Sequences that contain the provided bases. Search indexing is asynchronous, so results my be not be available immediately after creation.
'
operationId: searchRnaSequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/SearchBasesRequest'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequencesPaginatedList'
description: A filtered list of DNA Sequences
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Search RNA Sequences
tags:
- RNA Sequences
/rna-sequences:unarchive:
post:
description: Unarchive RNA sequences
operationId: unarchiveRNASequences
requestBody:
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequencesUnarchive'
responses:
'200':
content:
application/json:
schema:
$ref: '#/components/schemas/RnaSequencesArchivalChange'
description: OK
'400':
content:
application/json:
schema:
$ref: '#/components/schemas/BadRequestError'
description: Bad Request
summary: Unarchive RNA sequences
tags:
- RNA Sequences
components:
schemas:
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
Fields:
additionalProperties:
$ref: '#/components/schemas/Field'
type: object
RnaSequencePart:
allOf:
- $ref: '#/components/schemas/NucleotideSequencePart'
- properties:
strand:
example: 1
maximum: 1
minimum: 1
type: integer
type: object
SearchBasesRequest:
additionalProperties: false
properties:
archiveReason:
default: NOT_ARCHIVED
enum:
- NOT_ARCHIVED
- Other
- Archived
type: string
bases:
example: GATTACAA
minLength: 8
type: string
nextToken:
type: string
pageSize:
default: 50
maximum: 100
minimum: 0
type: integer
registryId:
description: 'ID of a registry. Restricts results to those registered in this registry. Specifying `null` returns unregistered items.
'
example: src_pwKo8pHh
nullable: true
type: string
schemaId:
description: 'ID of the nucleotide sequence''s schema.
'
example: ts_Y6t0Zbhg
type: string
sort:
default: modifiedAt:desc
enum:
- modifiedAt:asc
- modifiedAt:desc
- name:asc
- name:desc
type: string
required:
- bases
type: object
CustomField:
properties:
value:
type: string
type: object
RnaSequenceBulkUpdate:
additionalProperties: false
allOf:
- properties:
id:
type: string
type: object
- $ref: '#/components/schemas/RnaSequenceBaseRequest'
NucleotideSequencePart:
properties:
end:
description: 0-based exclusive end index. The end of the sequence is always represented as 0.
type: integer
sequenceId:
example: seq_VfVOART1
type: string
start:
description: 0-based inclusive start index.
type: integer
type: object
BadRequestError:
properties:
error:
allOf:
- $ref: '#/components/schemas/BaseError'
- properties:
type:
enum:
- invalid_request_error
type: string
type: object
SequenceFeatureCustomField:
description: A name and value pair associated with a sequence feature (annotation or translation). For genbank imports, these are the qualifiers associated with each feature.
properties:
name:
description: Name of the custom field
type: string
value:
description: Value of the custom field
type: string
type: object
SequenceFeatureBase:
properties:
color:
description: Hex color code used when displaying this feature in the UI.
example: '#F58A5E'
type: string
customFields:
items:
$ref: '#/components/schemas/SequenceFeatureCustomField'
maxItems: 100
type: array
name:
maxLength: 2048
type: string
notes:
example: Cong et al Science. 2013 Jan 3.
maxLength: 10000
type: string
type: object
SchemaFieldsQueryParam:
additionalProperties: true
example:
schemaField.Cell Count: '>= 10 AND <= 50'
schemaField.Experiment: MyExperiment
schemaField.Started On: <= 2023-05-23T00:00:00Z
type: object
BaseError:
properties:
message:
type: string
type:
type: string
userMessage:
type: string
type: object
RnaSequenceUpdate:
additionalProperties: false
allOf:
- $ref: '#/components/schemas/RnaSequenceBaseRequest'
- $ref: '#/components/schemas/RnaSequenceRequestRegistryFields'
ArchiveRecord:
properties:
reason:
example: Made in error
type: string
type: object
RnaSequenceCreate:
additionalProperties: false
allOf:
- $ref: '#/components/schemas/RnaSequenceBaseRequestForCreate'
- $ref: '#/components/schemas/CreateEntityIntoRegistry'
FieldType:
enum:
- dna_sequence_link
- aa_sequence_link
- custom_entity_link
- entity_link
- mixture_link
- molecule_link
- dropdown
- part_link
- translation_link
- aa_part_link
- base_molecule_link
- blob_link
- text
- long_text
- batch_link
- storage_link
- entry_link
- assay_request_link
- assay_result_link
- assay_run_link
- boolean
- float
- integer
- datetime
- date
- json
type: string
RnaSequencesArchivalChange:
description: 'IDs of all RNA Sequences that were archived or unarchived, grouped by resource type.
'
properties:
rnaSequenceIds:
items:
type: string
type: array
type: object
RnaSequencesArchive:
additionalProperties: false
description: 'The request body for archiving RNA sequences.
'
properties:
reason:
$ref: '#/components/schemas/EntityArchiveReason'
rnaSequenceIds:
items:
type: string
type: array
required:
- reason
- rnaSequenceIds
type: object
RnaSequenceBaseRequestForCreate:
additionalProperties: false
allOf:
- $ref: '#/components/schemas/RnaSequenceBaseRequest'
- required:
- name
NamingStrategy:
description: 'Specifies the behavior for automatically generated names when registering an entity.
- NEW_IDS: Generate new registry IDs
- IDS_FROM_NAMES: Generate registry IDs based on entity names
- DELETE_NAMES: Generate new registry IDs and replace name with registry ID
- SET_FROM_NAME_PARTS: Generate new registry IDs, rename according to name template, and keep old name as alias
- REPLACE_NAMES_FROM_PARTS: Generate new registry IDs, and replace name according to name template
- KEEP_NAMES: Keep existing entity names as registry IDs
- REPLACE_ID_AND_NAME_FROM_PARTS: Generate registry IDs and names according to name template
'
enum:
- NEW_IDS
- IDS_FROM_NAMES
- DELETE_NAMES
- SET_FROM_NAME_PARTS
- REPLACE_NAMES_FROM_PARTS
- KEEP_NAMES
- REPLACE_ID_AND_NAME_FROM_PARTS
type: string
UserSummary:
allOf:
- $ref: '#/components/schemas/PartySummary'
- example:
handle: lpasteur
id: ent_a0SApq3z
name: Louis Pasteur
MatchBasesRequest:
additionalProperties: false
properties:
archiveReason:
default: NOT_ARCHIVED
enum:
- NOT_ARCHIVED
- Other
- Archived
type: string
bases:
type: string
nextToken:
type: string
pageSize:
default: 50
maximum: 100
minimum: 0
type: integer
registryId:
description: 'ID of a registry. Restricts results to those registered in this registry. Specifying `null` returns unregistered items.
'
nullable: true
type: string
sort:
default: modifiedAt:desc
enum:
- modifiedAt:asc
- modifiedAt:desc
- name:asc
- name:desc
type: string
required:
- bases
type: object
RnaSequencesPaginatedList:
properties:
nextToken:
type: string
rnaSequences:
items:
$ref: '#/components/schemas/RnaSequence'
type: array
type: object
Translation:
allOf:
- $ref: '#/components/schemas/SequenceFeatureBase'
- properties:
aminoAcids:
readOnly: true
type: string
coerceStartCodonToMethionine:
default: false
description: Whether to override the translation of the start codon to Methionine. Has no effect when the start codon already translates to Methionine.
type: boolean
en
# --- truncated at 32 KB (45 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-rna-sequences-api-openapi.yml