Benchling Enzyme List API

openapi: 3.2.0
info:
  title: Benchling Enzyme List API
  version: 2.0.0
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  description: 'Operations tagged EnzymeList across 2 of this provider''s published API definitions: benchling-openapi.yml, benchling-v3-openapi.yaml. Each path carries the servers of the definition it was published in.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'Represents a user-curated collection of restriction enzymes for molecular cloning workflows.

    EnzymeLists allow users and organizations to organize commonly used enzymes into named groups

    for easy access when planning restriction digests, cloning strategies, or analyzing DNA

    sequences. Each list has an owner (either a user or organization) who controls access

    permissions. See `Enzyme` for the individual restriction enzymes that can be added to a list.'
  name: EnzymeList
  x-bnch-organization: Benchling
  x-displayName: Enzyme List
paths:
  /enzyme-list:
    post:
      description: Create EnzymeList.
      operationId: EnzymeList.Create
      parameters:
      - description: Set to true to access beta operations via /api/v3.
        in: header
        name: EARLY-ACCESS
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateEnzymeListInput'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnzymeList'
          description: Created
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Create EnzymeList
      tags:
      - EnzymeList
    servers:
    - url: /api/v3
  /enzyme-list/items:
    get:
      description: List EnzymeList items.
      operationId: EnzymeList.List
      parameters:
      - $ref: '#/components/parameters/createdAt.gt'
      - $ref: '#/components/parameters/createdAt.gte'
      - $ref: '#/components/parameters/createdAt.lt'
      - $ref: '#/components/parameters/createdAt.lte'
      - $ref: '#/components/parameters/id.anyOf'
      - $ref: '#/components/parameters/modifiedAt.gt'
      - $ref: '#/components/parameters/modifiedAt.gte'
      - $ref: '#/components/parameters/modifiedAt.lt'
      - $ref: '#/components/parameters/modifiedAt.lte'
      - $ref: '#/components/parameters/nextToken'
      - $ref: '#/components/parameters/omit'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/returning'
      - description: 'Method by which to order results. Valid sorts are: createdAt (created time, oldest first) and modifiedAt (modified time, oldest first). Use :asc or :desc to specify ascending or descending order. Default is modifiedAt:desc.'
        in: query
        name: sort
        schema:
          default: modifiedAt:desc
          enum:
          - createdAt:asc
          - createdAt:desc
          - modifiedAt:asc
          - modifiedAt:desc
          type: string
      - description: Set to true to access beta operations via /api/v3.
        in: header
        name: EARLY-ACCESS
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnzymeListPaginatedList'
          description: OK
          headers: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: List EnzymeList items
      tags:
      - EnzymeList
    servers:
    - url: /api/v3
  /enzyme-list/{enzyme_list_id}:
    get:
      description: Get a single EnzymeList by ID.
      operationId: EnzymeList.Get
      parameters:
      - description: ID of the EnzymeList.
        in: path
        name: enzyme_list_id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/returning'
      - $ref: '#/components/parameters/omit'
      - description: Set to true to access beta operations via /api/v3.
        in: header
        name: EARLY-ACCESS
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnzymeList'
          description: OK
          headers: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Get EnzymeList by ID
      tags:
      - EnzymeList
    patch:
      description: Update EnzymeList.
      operationId: EnzymeList.Update
      parameters:
      - description: ID of the EnzymeList.
        in: path
        name: enzyme_list_id
        required: true
        schema:
          type: string
      - description: Set to true to access beta operations via /api/v3.
        in: header
        name: EARLY-ACCESS
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateEnzymeListInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnzymeList'
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Update EnzymeList
      tags:
      - EnzymeList
    servers:
    - url: /api/v3
  /enzyme-list/{enzyme_list_id}/enzymes/items:
    get:
      description: List Enzyme items.
      operationId: EnzymeList.enzymes.List
      parameters:
      - description: ID of the EnzymeList.
        in: path
        name: enzyme_list_id
        required: true
        schema:
          type: string
      - description: Set to true to access beta operations via /api/v3.
        in: header
        name: EARLY-ACCESS
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EnzymeUnpaginatedList'
          description: OK
          headers: {}
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: List Enzyme items
      tags:
      - EnzymeList
    servers:
    - url: /api/v3
  /enzyme-list:batch-create:
    post:
      description: Batch create EnzymeList synchronously in one transaction. Maximum 25 items per request.
      operationId: EnzymeList.BatchCreate
      parameters:
      - description: Set to true to access beta operations via /api/v3.
        in: header
        name: EARLY-ACCESS
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                items:
                  items:
                    $ref: '#/components/schemas/CreateEnzymeListInput'
                  maxItems: 25
                  minItems: 1
                  type: array
              required:
              - items
              type: object
      responses:
        '201':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/EnzymeList'
                    type: array
                required:
                - items
                type: object
          description: Created
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Batch create EnzymeList
      tags:
      - EnzymeList
    servers:
    - url: /api/v3
  /enzyme-list:batch-update:
    patch:
      description: Batch update EnzymeList synchronously in one transaction. Maximum 25 items per request.
      operationId: EnzymeList.BatchUpdate
      parameters:
      - description: Set to true to access beta operations via /api/v3.
        in: header
        name: EARLY-ACCESS
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                items:
                  items:
                    $ref: '#/components/schemas/UpdateEnzymeListInputWithPathParams'
                  maxItems: 25
                  minItems: 1
                  type: array
              required:
              - items
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/EnzymeList'
                    type: array
                required:
                - items
                type: object
          description: OK
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Batch update EnzymeList
      tags:
      - EnzymeList
    servers:
    - url: /api/v3
  /enzyme-list:bulk-create:
    post:
      description: Bulk create EnzymeList.
      operationId: EnzymeList.BulkCreate
      parameters:
      - description: Set to true to access beta operations via /api/v3.
        in: header
        name: EARLY-ACCESS
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkImport'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncTaskLink'
          description: Task started
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Bulk create EnzymeList
      tags:
      - EnzymeList
    servers:
    - url: /api/v3
  /enzyme-list:bulk-update:
    patch:
      description: Bulk update EnzymeList.
      operationId: EnzymeList.BulkUpdate
      parameters:
      - description: Set to true to access beta operations via /api/v3.
        in: header
        name: EARLY-ACCESS
        required: false
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/BulkImport'
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncTaskLink'
          description: Task started
        '400':
          $ref: '#/components/responses/BadRequest'
        '403':
          $ref: '#/components/responses/Forbidden'
        '404':
          $ref: '#/components/responses/NotFound'
        '409':
          $ref: '#/components/responses/Conflict'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Bulk update EnzymeList
      tags:
      - EnzymeList
    servers:
    - url: /api/v3
components:
  schemas:
    EnzymeList:
      description: 'Represents a user-curated collection of restriction enzymes for molecular cloning workflows.

        EnzymeLists allow users and organizations to organize commonly used enzymes into named groups

        for easy access when planning restriction digests, cloning strategies, or analyzing DNA

        sequences. Each list has an owner (either a user or organization) who controls access

        permissions. See `Enzyme` for the individual restriction enzymes that can be added to a list.'
      properties:
        __typename:
          type: string
        createdAt:
          description: DateTime the Enzyme List was created
          format: datetime
          type: string
        description:
          description: Description of the Enzyme List
          type:
          - 'null'
          - string
        enzymes:
          description: List of Enzymes that are part of this Enzyme List
          format: uri
          type: string
        id:
          description: Id of the Enzyme List
          type: string
        modifiedAt:
          description: DateTime the Enzyme List was last modified
          format: datetime
          type: string
        name:
          description: Name of the Enzyme List
          type: string
        owner:
          $ref: '#/components/schemas/OwnerRef'
          description: User or Organization owner
      type: object
    OwnerRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    EnzymeUnpaginatedList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/Enzyme'
          type: array
      type: object
    GeneralError:
      properties:
        detail:
          type:
          - 'null'
          - string
          - object
        instance:
          type: string
        invalidId:
          type: string
        status:
          type: integer
        title:
          type:
          - 'null'
          - string
        type:
          type: string
      required:
      - type
      - title
      - detail
      - status
      - instance
      type: object
    EnzymeListPaginatedList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/EnzymeList'
          type: array
        nextToken:
          type:
          - string
          - 'null'
      type: object
    TooManyRequestsError:
      properties:
        detail:
          type:
          - 'null'
          - string
          - object
        instance:
          type: string
        invalidId:
          type: string
        status:
          type: integer
        title:
          type:
          - 'null'
          - string
        type:
          type: string
      required:
      - type
      - title
      - detail
      - status
      - instance
      type: object
    UpdateEnzymeListInputWithPathParams:
      additionalProperties: false
      example:
        description: Revised set of go-to restriction enzymes
        enzymeIds:
        - enz_pEcJJ79A
        id: enzl_jwM0BCyX
        name: Updated cloning enzymes
      properties:
        description:
          description: Description of the Enzyme List
          type:
          - 'null'
          - string
        enzymeIds:
          description: API IDs of enzymes from the global restriction-enzyme catalog. When provided, replaces the entire member set (use an empty array to remove all enzymes). Each ID must be valid and IDs must not repeat within the list.
          items:
            type: string
          type: array
        id:
          type: string
        name:
          description: Leading and trailing whitespace is stripped. Must be non-empty and at most 128 characters. Names are unique per owner (case-insensitive). Duplicate names within the same batch request are rejected when they target the same owner.
          type: string
      required:
      - id
      type: object
    CutSiteDetail:
      description: 'Describes the cleavage pattern of a restriction enzyme relative to its recognition site.

        The position field indicates where the 5'' strand is cut, while offset specifies the distance

        from position where the 3'' strand is cut. A zero offset produces blunt ends; non-zero offsets

        create sticky ends (overhangs). Enzymes that cut once have a single CutSiteDetail, while

        rare double-cutting enzymes have two. This information is essential for predicting fragment

        sizes and compatible ends when designing cloning strategies.'
      properties:
        __typename:
          type: string
        offset:
          description: Location, relative to `position`, where the 3' cut is made.
          type: integer
        position:
          description: Location, relative to the restriction site bases, where the 5' cut is made.
          type: integer
      type: object
    CreateEnzymeListInput:
      additionalProperties: false
      example:
        description: Frequently used restriction enzymes for molecular cloning
        enzymeIds:
        - enz_pEcJJ79A
        - enz_xHoII12B
        name: Common cloning enzymes
        ownerId: ent_aBcDeFgH
      properties:
        description:
          description: Description of the Enzyme List
          type:
          - 'null'
          - string
        enzymeIds:
          description: API IDs of enzymes from the global restriction-enzyme catalog to include in the new list. Omit to create an empty list. Each ID must be valid and IDs must not repeat within the list.
          items:
            type: string
          type: array
        name:
          description: Leading and trailing whitespace is stripped. Must be non-empty and at most 128 characters. Names are unique per owner (case-insensitive). Duplicate names within the same batch request are rejected when they target the same owner.
          type: string
        ownerId:
          description: The API ID of the user or organization that owns the enzyme list.
          type: string
      required:
      - name
      - ownerId
      type: object
    Enzyme:
      description: 'Represents a restriction enzyme from Benchling''s global catalog of commercially available

        enzymes. Restriction enzymes (also known as restriction endonucleases) are molecular scissors

        that recognize specific DNA sequences and cleave the DNA at defined positions. Each enzyme

        has a recognition sequence (restrictionSiteBases), such as GAATTC for EcoRI, and cut site

        details (see CutSiteDetail) specifying where the enzyme cuts relative to that recognition

        site. Enzymes can produce blunt ends or sticky ends (overhangs) depending on their cut

        pattern. Users can organize frequently used enzymes into EnzymeLists for convenient access

        during cloning workflow design.'
      properties:
        __typename:
          type: string
        cutSites:
          description: Either one (for single cutters) or two (for double cutters) cut details.
          items:
            $ref: '#/components/schemas/CutSiteDetail'
          type: array
        id:
          description: Id of the Enzyme
          type: string
        isoschizomers:
          description: Other enzymes in the catalog that recognize the same restriction site.
          format: uri
          type: string
        name:
          description: The name of the Enzyme, like EcoRI.
          type: string
        restrictionSiteBases:
          description: The DNA bases recognized by the Enzyme.
          type: string
      type: object
    UpdateEnzymeListInput:
      additionalProperties: false
      example:
        description: Revised set of go-to restriction enzymes
        enzymeIds:
        - enz_pEcJJ79A
        name: Updated cloning enzymes
      properties:
        description:
          description: Description of the Enzyme List
          type:
          - 'null'
          - string
        enzymeIds:
          description: API IDs of enzymes from the global restriction-enzyme catalog. When provided, replaces the entire member set (use an empty array to remove all enzymes). Each ID must be valid and IDs must not repeat within the list.
          items:
            type: string
          type: array
        name:
          description: Leading and trailing whitespace is stripped. Must be non-empty and at most 128 characters. Names are unique per owner (case-insensitive). Duplicate names within the same batch request are rejected when they target the same owner.
          type: string
      type: object
    AsyncTaskLink:
      properties:
        pollingUri:
          format: uri
          type: string
        taskId:
          type: string
      type: object
    BulkImport:
      example:
        fileId: scrfile_jdf8BV24kLmN
      properties:
        fileId:
          description: The API ID of the scratch file (`scrfile_XXXXXXXX`) containing the items to import. The referenced file must be a scratch file whose upload has completed successfully.
          type: string
      required:
      - fileId
      type: object
    InternalServerError:
      properties:
        detail:
          type:
          - 'null'
          - string
          - object
        errorId:
          type: string
        instance:
          type: string
        status:
          type: integer
        title:
          type:
          - 'null'
          - string
        type:
          type: string
      required:
      - type
      - title
      - detail
      - status
      - instance
      type: object
    GeneralError_2:
      properties:
        detail:
          type:
          - 'null'
          - string
          - object
        instance:
          type: string
        status:
          type: integer
        title:
          type:
          - 'null'
          - string
        type:
          type: string
      required:
      - type
      - title
      - detail
      - status
      - instance
      type: object
    EnzymeListPaginatedList_2:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/EnzymeList'
          type: array
        nextToken:
          type: string
      type: object
  responses:
    InternalServerError:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
      description: Internal Server Error
    BadRequest:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Bad Request
    NotFound:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Not Found
    Forbidden:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Forbidden
    Conflict:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Conflict
    TooManyRequests:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/TooManyRequestsError'
      description: Too Many Requests
      headers:
        Retry-After:
          description: Minimum number of seconds to wait before retrying. Only included when the request exceeded a rate limit specific to the caller. Limits shared with other callers, such as tenant-wide limits, omit this header because the wait depends on their traffic.
          required: false
          schema:
            minimum: 1
            type: integer
    TooManyRequests_2:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError_2'
      description: Too Many Requests
  parameters:
    modifiedAt.gte:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or after the specified time. e.g. >= 2017-04-30.
      in: query
      name: modifiedAt.gte
      schema:
        format: datetime
        type: string
    createdAt.lte:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or before the specified time. e.g. <= 2017-04-30.
      in: query
      name: createdAt.lte
      schema:
        format: datetime
        type: string
    omit:
      description: Comma-separated list of top-level fields to omit from each returned item. Cannot overlap with returning.
      explode: false
      in: query
      name: omit
      schema:
        items:
          type: string
        type: array
    modifiedAt.lte:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or before the specified time. e.g. <= 2017-04-30.
      in: query
      name: modifiedAt.lte
      schema:
        format: datetime
        type: string
    createdAt.gt:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created after the specified time. e.g. > 2017-04-30.
      in: query
      name: createdAt.gt
      schema:
        format: datetime
        type: string
    nextToken:
      description: Token for pagination
      in: query
      name: nextToken
      schema:
        type: string
    modifiedAt.gt:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified after the specified time. e.g. > 2017-04-30.
      in: query
      name: modifiedAt.gt
      schema:
        format: datetime
        type: string
    pageSize:
      description: Number of results to return. Defaults to 50, maximum of 100.
      in: query
      name: pageSize
      schema:
        type: integer
    modifiedAt.lt:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified before the specified time. e.g. < 2017-04-30.
      in: query
      name: modifiedAt.lt
      schema:
        format: datetime
        type: string
    returning:
      description: Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit.
      explode: false
      in: query
      name: returning
      schema:
        items:
          type: string
        type: array
    createdAt.gte:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or after the specified time. e.g. >= 2017-04-30.
      in: query
      name: createdAt.gte
      schema:
        format: datetime
        type: string
    createdAt.lt:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created before the specified time. e.g. < 2017-04-30.
      in: query
      name: createdAt.lt
      schema:
        format: datetime
        type: string
    id.anyOf:
      description: Restricts results to those matching any of the specified IDs. Comma-separated list.
      explode: false
      in: query
      name: id.anyOf
      schema:
        items:
          type: string
        maxItems: 100
        type: array
  securitySchemes:
    BearerAuth:
      description: Use a short-lived V3 API Explorer token.
      scheme: bearer
      type: http
      x-fern-playground-description: Copy a short-lived V3 API Explorer token from the user's settings page
    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: /oauth/token
      type: oauth2
x-refined-from:
- benchling-openapi.yml
- benchling-v3-openapi.yaml