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: '#/components/schemas/FieldValueWithResolution'
            nullable: true
        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
    DnaSequencesPaginatedList:
      properties:
        dnaSequences:
          items:
            $ref: '#/components/schemas/DnaSequence'
          type: array
        nextToken:
          type: string
      type: object
    DnaSequenceRequestRegistryFields:
      properties:
        entityRegistryId:
          type: string
      type: object
    CustomField:
      properties:
        value:
          type: string
      type: object
    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
    DnaAnnotation:
      allOf:
      - $ref: '#/components/schemas/SequenceFeatureBase'
      - properties:
          end:
            description: 0-based exclusive end index. The end of the sequence is always represented as 0.
            type: integer
          start:
            description: 0-based inclusive start index.
            type: integer
          strand:
            maximum: 1
            minimum: -1
            type: integer
          type:
            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
    ArchiveRecordSet:
      additionalProperties: false
      description: Currently, we only support setting a null value for archiveRecord, which unarchives the item
      example: null
      nullable: true
      type: object
    DnaSequenceBaseRequest:
      properties:
        aliases:
          description: Aliases to add to the DNA sequence
          items:
            type: string
          type: array
        annotations:
          description: 'Annotations to create on the DNA sequence.

            '
          items:
            $ref: '#/components/schemas/DnaAnnotation'
          type: array
        authorIds:
          description: IDs of users to set as the DNA sequence's authors.
          items:
            type: string
          type: array
        bases:
          description: 'Base pairs for the DNA sequence.

            '
          type: string
        customFields:
          allOf:
          - $ref: '#/components/schemas/CustomFields'
          description: 'Custom fields to add to the DNA sequence. Every field should have its name as a key, mapping to an object with information about the value of the field.

            '
        fields:
          allOf:
          - $ref: '#/components/schemas/Fields'
          description: 'Fields to set on the DNA sequence. Must correspond with the schema''s field definitions. Every field should have its name as a key, mapping to an object with information about the value of the field.

            '
        folderId:
          description: 'ID of the folder containing the DNA sequence.

            '
          type: string
        isCircular:
          description: 'Whether the DNA sequence is circular or linear.

            '
          type: boolean
        name:
          description: 'Name of the DNA sequence.

            '
          type: string
        parts:
          items:
            $ref: '#/components/schemas/DnaSequencePart'
          type: array
        primers:
          items:
            $ref: '#/components/schemas/Primer'
          type: array
        schemaId:
          description: 'ID of the DNA sequence''s schema.

            '
          type: string
        translations:
          description: 'Translations to create on the DNA sequence. Translations are specified by either a combination of ''start'' and ''end'' fields, or a list of regions. Both cannot be provided.

            '
          items:
            $ref: '#/components/schemas/Translation'
          type: array
      type: object
    DnaSequenceCreate:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/DnaSequenceBaseRequestForCreate'
      - $ref: '#/components/schemas/CreateEntityIntoRegistry'
    SchemaFieldsQueryParam:
      additionalProperties: true
      example:
        schemaField.Cell Count: '>= 10 AND <= 50'
        schemaField.Experiment: MyExperiment
        schemaField.Started On: <= 2023-05-23T00:00:00Z
      type: object
    DnaSequencesBulkUpdateRequest:
      additionalProperties: false
      properties:
        dnaSequences:
          items:
            $ref: '#/components/schemas/DnaSequenceBulkUpdate'
          type: array
      type: object
    ReducedPattern:
      additionalProperties: false
      description: 'DNA patterns to avoid during optimization. Supports two formats: 1) DNA base patterns: strings of ATGC bases (case-insensitive, e.g., "ATGC" or "gat") 2) Repeat patterns: format "nxkmer" specifying n repeats of k-sized sequences (e.g., "3x4mer" matches 3 consecutive 4-base repeats). Maximum total length for repeat patterns is 50 bases (n * k ≤ 50).

        If avoidReverseComplement is true, the pattern''s reverse complement will also be avoided. Note: avoidReverseComplement cannot be true for repeat patterns (nxkmer format).

        '
      properties:
        avoidReverseComplement:
          default: false
          type: boolean
        pattern:
          type: string
      type: object
    ArchiveRecord:
      properties:
        reason:
          example: Made in error
          type: string
      type: object
    OptimizeCodons:
      additionalProperties: false
      properties:
        avoidedCutsiteEnzymeIds:
          description: 'List of enzyme IDs whose recognition sites will be avoided when creating the optimized sequence.

            '
          items:
            type: string
          type: array
        codonUsageTableId:
          description: ID of the codon usage table representing the target organism.
          type: string
        dnaSequenceIds:
          description: IDs of DNA sequences to codon-optimize.
          items:
            type: string
          type: array
        folderId:
          description: 'ID of the folder in which the optimized sequences will be saved.

            '
          type: string
        gcContent:
          default: ANY
          description: 'The amount of GC content in the optimized sequence. LOW is defined as below 0.33, MEDIUM as 0.33-0.66, and HIGH as above 0.66. If neither gcContent nor gcContentRange is specified, the optimization will default to ANY (0-1). Cannot be specified together with gcContentRange.

            '
          enum:
          - ANY
          - LOW
          - MEDIUM
          - HIGH
          type: string
        gcContentRange:
          additionalProperties: false
          description: 'Custom GC content range for the optimized sequence, specified as decimal values between 0 and 1. The maximum must be greater than the minimum. Cannot be specified together with gcContent.

            '
          properties:
            max:
              description: Maximum GC content ratio (e.g., 0.6 for 60%)
              maximum: 1
              minimum: 0
              type: number
            min:
              description: Minimum GC content ratio (e.g., 0.4 for 40%)
              maximum: 1
              minimum: 0
              type: number
          type: object
        hairpinParameters:
          additionalProperties: false
          description: 'These parameters are applied in the AvoidHairpins specification in DNAChisel. If hairpinParameters is not specified, hairpins will not be avoided.

            '
          properties:
            stem:
              default: 20
              type: integer
            window:
              default: 200
              type: integer
          type: object
        method:
          default: MATCH_CODON_USAGE
          description: 'The codon optimization algorithm to use. Requires codonUsageTableId to be specified. MATCH_CODON_USAGE selects codons probabilistically based on the organism''s codon usage frequencies. USE_BEST_CODON always selects the most frequently used codon for each amino acid.

            '
          enum:
          - MATCH_CODON_USAGE
          - USE_BEST_CODON
          type: string
        reducedPatterns:
          description: 'List of patterns to avoid when creating the optimized sequence, on the coding strand only.

            '
          items:
            $ref: '#/components/schemas/ReducedPattern'
          type: array
        schemaId:
          description: ID of the optimized DNA sequences' schemas
          type: string
        shouldDepleteUridine:
          default: false
          description: 'If not specified, the optimization will default to false, and mRNA uridine depletion will not be performed.

            '
          type: boolean
      required:
      - dnaSequenceIds
      - folderId
      type: object
    BaseError:
      properties:
        message:
          type: string
        type:
          type: string
        userMessage:
          type: string
      type: object
    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
    FieldsWithResolution:
      additionalProperties:
        $ref: '#/components/schemas/FieldWithResolution'
      example:
        Linked Peptide:
          value: prtn_ObbdtGhC
        Linked Sequence:
          value:
            entityRegistryId: DNA001
        Linked Strains:
          value:
          - entityRegistryId: STRAIN001
          - entityRegistryId: STRAIN002
      type: object
    FieldValueWithResolution:
      oneOf:
      - type: string
      - type: boolean
      - type: number
      - items:
          type: string
        type: array
      - additionalProperties: false
        description: Look up an entity by its entity registry ID
        properties:
          entityRegistryId:
            type: string
        required:
        - entityRegistryId
        type: object
    DnaSequenceUpdate:
      additionalProperties: false
      allOf:
      - $ref: '#/components/schemas/DnaSequenceBaseRequest'
      - $ref: '#/components/schemas/DnaSequenceRequestRegistryFields'
    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
    DnaSequencesArchive:
      additionalProperties: false
      description: 'The request body for archiving DNA sequences.

        '
      properties:
        dnaSequenceIds:
          items:
            type: string
          type: array
        reason:
          $ref: '#/components/schemas/EntityArchiveReason'
      required:
      - reason
      - dnaSequenceIds
      type: object
    UserSummary:
      allOf:
      - $ref: '#/components/schemas/PartySummary'
      - example:
          handle: lpasteur
          id: ent_a0SApq3z
          name: Louis Pasteur
    DnaSequenceBulkUpsertRequest:
      allOf:
      - $ref: '#/components/schemas/EntityBulkUpsertBaseRequest'
      - $ref: '#/components/schemas/DnaSequenceBaseRequestForCreate'
      - required:
        - annotations
        - primers
    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
    DnaSequenceBulkUpdate:
      additionalProperties: false
      allOf:
      - properties:
          id:
            type: string
        type: object
      - $ref: '#/components/schemas/DnaSequenceBaseRequest'
    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
          end:
            description: 0-based exclusive end index. The end of the sequence is always represented as 0.
            type: integer
          geneticCode:
            default: STANDARD
            description: The genetic code to use when translating the nucleotide sequence into amino acids.
            enum:
            - STANDARD
            - VERTEBRATE_MITOCHONDRIAL
            - YEAST_MITOCHONDRIAL
            - MOLD_PROTOZOAN_COELENTERATE_MITOCHONDRIAL_MYCOPLASMA_SPIROPLASMA
            - INVERTEBRATE_MITOCHONDRIAL
            - CILIATE_DASYCLADACEAN_HEXAMITA_NUCLEAR
            - ECHINODERM_FLATWORM_MITOCHONDRIAL
            - EUPLOTID_NUCLEAR
            - BACTERIAL_ARCHAEAL_PLANT_PLASTID
            - ALTERNATIVE_YEAST_NUCLEAR
            - ASCIDIAN_MITOCHONDRIAL
            - ALTERNATIVE_FLATWORM_MITOCHONDRIAL
            - CHLOROPHYCEAN_MITOCHONDRIAL
            - TREMATODE_MITOCHONDRIAL
            - SCENEDESMUS_OBLIQUUS_MITOCHONDRIAL
            - THRAUSTOCHYTRIUM_MITOCHONDRIAL
            - RHABDOPLEURIDAE_MITOCHONDRIAL
            - CANDIDATE_DIVISION_SR1_GRACILIBACTERIA
            - PACHYSOLEN_TANNOPHILUS_NUCLEAR
            - MESODINIUM_NUCLEAR
            - PERITRICH_NUCLEAR
            - CEPHALODISCIDAE_MITOCHONDRIAL_UAA_TYR
            type: string
          regions:
            items:
              properties:
                end:
                  description: 0-based exclusive end index. The end of the sequence is always represented as 0.
                  type: integer
                start:
                  description: 0-based inclusive start index.
                  type: integer
              type: object
            type: array
          start:
            description: 0-based inclusive start index.
            type: integer
          strand:
            example: 1
            type: integer
        type: object
    Field:
      properties:
        displayValue:
          nullable: true
          readOnly: true
          type: string
        isMulti:
          readOnly: true
          type: boolean
        textValue:
          example: Amp
          nullable: true
          readOnly: true
          type: string
        type:
          allOf:
          - $ref: '#/components/schemas/FieldType'
          readOnly: true
        value:
          description: 'For single link fields, use the id of the item you want to link (eg. "seq_jdf8BV24").

            For multi-link fields, use an array of ids of the items you want to link (eg. ["seq_jdf8BV24"])

            '
          nullable: true
          oneOf:
          - type: string
          - type: boolean
          - type: number
          - type: object
          - items:
              type: string
            type: array
      required:
      - value
      type: object
    DnaSequenceTranscription:
      properties:
        end:
          description: 0-based exclusive end index. The end of the sequence is always represented as 0.
          type: integer
        sequenceId:
          description: Linked RNA sequence ID.
          example: seq_VfVOART1
          type: string
        start:
          description: 0-based inclusive start index.
          type: integer
        strand:
          example: 1
          maximum: 1
          minimum: -1
          type: integer
      type: object
    DnaSequencePart:
      allOf:
      - $ref: '#/components/schemas/NucleotideSequencePart'
      - properties:
          strand:
            example: 1
            maximum: 1
            minimum: -1
            type: integer
        type: object
    PartySummary:
      properties:
        handle:
          type: string
        id:
          type: string
        name:
          type: string
      type: object
    DnaSequenceBulkCreate:
      allOf:
      - $ref: '#/components/schemas/DnaSequenceCreate'
    DnaSequencesUnarchive:
      additionalProperties: false
      description: 'The request body for unarchiving DNA sequences.

        '
      properties:
        dnaSequenceIds:
          items:
            type: string
          type: array
      required:
      - dnaSequenceIds
      type: object
    DnaSequencesBulkCreateRequest:
      additionalProperties: false
      properties:
        dnaSequences:
          items:
            $ref: '#/components/schemas/DnaSequenceBulkCreate'
          maxItems: 1000
          type: array
      type: object
    AsyncTaskLink:
      properties:
        taskId:
          type: string
      type: object
    CustomFields:
      additionalProperties:
        $ref: '#/components/schemas/CustomField'
      example:
        Legacy ID:
          value: STR100
      type: object
    EntityBulkUpsertBaseRequest:
      allOf:
      - $ref: '#/components/schemas/EntityUpsertBaseRequest'
      - properties:
          entityRegistryId:
            description: Registry ID of the entity in Benchling.
            type: string
      - required:
        - entityRegistryId
    AutoAnnotateDnaSequences:
      additionalProperties: false
      properties:
        dnaSequenceIds:
          description: Array of DNA sequence IDs.
          items:
            type: string
          type: array
        featureLibraryIds:
          description: Array of feature library IDs.
          items:
            type: string
          type: array
      required:
      - dnaSequenceIds
      - featureLibraryIds
      type: object
    AutofillSequences:
      additionalProperties: false
      properties:
        dnaSequenceIds:
          description: Array of DNA sequence IDs.
          items:
            type: string
          type: array
      required:
      - dnaSequenceIds
      type: object
    DnaSequencesBulkGet:
      properties:
        dnaSequences:
          items:
            $ref: '#/components/schemas/DnaSequence'
          type: array
      type: object
    RegistrationOrigin:
      properties:
        originEntryId:
          nullable: true
          readOnly: true
          type: string
        registeredAt:
          format: date-time
          readOnly: true
          type: string
      type: object
    EntityUpsertBaseRequest:
      properties:
        archiveRecord:
          $ref: '#/components/schemas/ArchiveRecordSet'
        fields:
          $ref: '#/components/schemas/FieldsWithResolution'
        name:
          type: string
        registryId:
          type: string
        schemaId:
          type: string
      required:
      - registryId
      - name
      - schemaId
      type: object
    CreateEntityIntoRegistry:
      properties:
        entityRegistryId:
          description: 'Entity registry ID to set for the registered entity. Cannot specify both entityRegistryId and namingStrategy at the same time.

            '
          type: string
        folderId:
          description: ID of the folder containing the entity. Can be left empty when registryId is present.
          type: string
        namingStrategy:
          $ref: '#/components/schemas/NamingStrategy'
        registryId:
          description: 'Registry ID into which entity should be registered. this is the ID of the registry which was configured for a particular organization

            To get available registryIds, use the [/registries endpoint](#/Registry/listRegistries)


            Required in order for entities to be created directly in the registry.

            '
          type: string
      type: object
    DnaSequencesBulkUpsertRequest:
      additionalProperties: false
      maxItems: 1000
      properties:
        dnaSequences:
          items:
            $ref: '#/components/schemas/DnaSequenceBulkUpsertRequest'
          type: array
      required:
      - dnaSequences
      type: object
    DnaSequence:
      properties:
        aliases:
          items:
            type: string
          type: array
        annotations:
          items:
            $ref: '#/components/schemas/DnaAnnotation'
          type: array
        apiURL:
          description: The canonical url of the DNA Sequence in the API.
          example: https://benchling.com/api/v2/dna-sequences/seq_asQya4lk
          format: uri
          readOnly: true
          type: string
        archiveRecord:
          allOf:
          - $ref: '#/components/schemas/ArchiveRecord'
          nullable: true
        authors:
          items:
            $ref: '#/components/schemas/UserSummary'
          type: array
        bases:
          type: string
        createdAt:
          format: date-time
          readOnly: true
          type: string
        creator:
          $ref: '#/components/schemas/UserSummary'
        customFields:
          $ref: '#/components/schemas/CustomFields'
        dnaAlignmentIds:
          description: API IDs of Nucleotide Alignments involving the RNA sequence
          items:
            type: string
          type: array
        entityRegistryId:
          nullable: true
          type: string
        fields:
          $ref: '#/components/schemas/Fields'
        folderId:
          nullable: true
          type: string
        id:
          type: string
        isCircular:
          type: boolean
        length:
          type: integer
        modifiedAt:
          format: date-time
          readOnly: true
          type: string
        name:
          type: string
        parts:
          items:
            $ref: '#/components/schemas/DnaSequencePart'
          type: array
        primers:
          items:
            $ref: '#/components/schemas/Primer'
          type: array
        registrationOrigin:
          allOf:
          - $ref: '#/components/schemas/RegistrationOrigin'
          nullable: true
          readOnly: true
        registryId:
          nullable: true
          type: string
        schema:
          allOf:
          - $ref: '#/components/schemas/SchemaSummary'
          nullable: true
        transcriptions:
          items:
            $ref: '#/components/schemas/DnaSequenceTranscription'
          type: array
        translations:
          items:
            $ref: '#/components/schemas/Translation'
          type: array
        url:
          description: The path of the web URL, omitting the tenant domain
          type: string
        webURL:
          readOnly: true
          type: string
      type: object
    SchemaSummary:
      properties:
        id:
          type: string
        name:
          type: string
      type: object
    EntityArchiveReason:
      description: 'The reason for archiving the provided entities. Accepted reasons may differ based on tenant configuration.

        '
      enum:
      - Made in error
      - Retired
      - Expended
      - Shipped
      - Contaminated
      - Expired
      - Missing
      - Other
      type: string
  securitySchemes:
    basicApiKeyAuth:
      description: Use issued API key for standard access to the API
      scheme: basic
      type: http
    basicClientIdSecretAuth:
      description: Auth used as part of client credentials OAuth flow prior to receiving a bearer token.
      scheme: basic
      type: http
    oAuth:
      description: OAuth2 Client Credentials flow intended for service access
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /api/v2/token
      type: oauth2
externalDocs:
  description: Additional API Documentation
  url: https://docs.benchling.com