openapi: 3.2.0
info:
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Benchling Protein Format API
  version: 2.0.0
  description: 'A ProteinFormat defines the structural template for a class of proteins, specifying the

    arrangement of chains and domains. Formats can be built-in (e.g., IgG1, Fab, scFv) or

    custom-defined by users.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A ProteinFormat defines the structural template for a class of proteins, specifying the

    arrangement of chains and domains. Formats can be built-in (e.g., IgG1, Fab, scFv) or

    custom-defined by users.'
  name: ProteinFormat
  x-bnch-organization: Benchling
paths:
  /protein-format:
    post:
      description: Create ProteinFormat.
      operationId: ProteinFormat.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/CreateProteinFormatInput'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProteinFormat'
          description: Created
        '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: Create ProteinFormat
      tags:
      - ProteinFormat
      x-bnch-rate-limit-tier: 4
  /protein-format/items:
    get:
      description: List ProteinFormat items.
      operationId: ProteinFormat.List
      parameters:
      - $ref: '#/components/parameters/archiveReason.anyOf'
      - $ref: '#/components/parameters/archived.anyOf'
      - $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/ProteinFormatPaginatedList'
          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 ProteinFormat items
      tags:
      - ProteinFormat
      x-bnch-rate-limit-tier: 4
  /protein-format/{protein_format_id}:
    get:
      description: Get a single ProteinFormat by ID.
      operationId: ProteinFormat.Get
      parameters:
      - description: ID of the ProteinFormat.
        in: path
        name: protein_format_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/ProteinFormat'
          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 ProteinFormat by ID
      tags:
      - ProteinFormat
      x-bnch-rate-limit-tier: 5
    patch:
      description: Update ProteinFormat.
      operationId: ProteinFormat.Update
      parameters:
      - description: ID of the ProteinFormat.
        in: path
        name: protein_format_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/UpdateProteinFormatInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ProteinFormat'
          description: OK
        '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: Update ProteinFormat
      tags:
      - ProteinFormat
      x-bnch-rate-limit-tier: 4
  /protein-format:batch-create:
    post:
      description: Batch create ProteinFormat synchronously in one transaction. Maximum 25 items per request.
      operationId: ProteinFormat.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/CreateProteinFormatInput'
                  maxItems: 25
                  minItems: 1
                  type: array
              required:
              - items
              type: object
      responses:
        '201':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/ProteinFormat'
                    type: array
                required:
                - items
                type: object
          description: Created
        '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: Batch create ProteinFormat
      tags:
      - ProteinFormat
      x-bnch-rate-limit-tier: 3
  /protein-format:batch-update:
    patch:
      description: Batch update ProteinFormat synchronously in one transaction. Maximum 25 items per request.
      operationId: ProteinFormat.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/UpdateProteinFormatInputWithPathParams'
                  maxItems: 25
                  minItems: 1
                  type: array
              required:
              - items
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/ProteinFormat'
                    type: array
                required:
                - items
                type: object
          description: OK
        '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: Batch update ProteinFormat
      tags:
      - ProteinFormat
      x-bnch-rate-limit-tier: 3
  /protein-format:bulk-create:
    post:
      description: Bulk create ProteinFormat.
      operationId: ProteinFormat.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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Bulk create ProteinFormat
      tags:
      - ProteinFormat
      x-bnch-rate-limit-tier: 2
  /protein-format:bulk-update:
    patch:
      description: Bulk update ProteinFormat.
      operationId: ProteinFormat.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'
        '429':
          $ref: '#/components/responses/TooManyRequests'
        '500':
          $ref: '#/components/responses/InternalServerError'
      summary: Bulk update ProteinFormat
      tags:
      - ProteinFormat
      x-bnch-rate-limit-tier: 2
components:
  parameters:
    pageSize:
      description: Number of results to return. Defaults to 50, maximum of 100.
      in: query
      name: pageSize
      schema:
        type: integer
    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
    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
    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
    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
    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.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
    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
    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
    archiveReason.anyOf:
      description: Restricts items to those with any of the specified archive reasons. Use "NOT_ARCHIVED" to filter for unarchived items. Use "ANY_ARCHIVED" to filter for archived items regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived. Comma-separated list.
      explode: false
      in: query
      name: archiveReason.anyOf
      schema:
        items:
          type: string
        maxItems: 10
        type: array
    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
    archived.anyOf:
      description: If true, returns archived items. If false, returns unarchived items. If both true and false, returns archived and unarchived items. Comma-separated list.
      explode: false
      in: query
      name: archived.anyOf
      schema:
        items:
          type: boolean
        maxItems: 2
        type: array
    nextToken:
      description: Token for pagination
      in: query
      name: nextToken
      schema:
        type: string
    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
  responses:
    NotFound:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Not Found
    TooManyRequests:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Too Many Requests
    BadRequest:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Bad Request
    Forbidden:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Forbidden
    InternalServerError:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
      description: Internal Server Error
  schemas:
    ProteinFormatChainPosition:
      description: 'Defines each instance of a polypeptide chain within a `ProteinFormat`, specifying the chain type and

        its constituent domains. Each chain position has a unique ref identifier and lists the domain positions

        (see `ProteinFormatDomainPosition`) that compose it in order from N-terminus to C-terminus.

        For example, a heavy chain position might reference domain positions [VH, CH1, Hinge, CH2, CH3].'
      properties:
        __typename:
          type: string
        domainPositions:
          description: A list of all the domain positions that make up the chain position, in order
          items:
            $ref: '#/components/schemas/ProteinFormatDomainPosition'
          type: array
        ref:
          description: 'A unique identifier for a physical component (chain or domain) in a protein format.

            This is used to form a HELM reference that is used in the protein''s complex polymer structure.'
          type: integer
        type:
          description: Type of the chain.
          enum:
          - HEAVY
          - LIGHT
          - NONE
          - ALPHA
          - BETA
          - JOINING
          type: string
      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
    ProteinFormatChain:
      description: 'A chain in a protein format, representing the slot where a polypeptide chain can be used in an entity of

        this format. Chains are uniquely identified by their label in the format.

        Chains can have multiplicity, meaning there are multiple physical instances of the same chain in a protein of

        this format.'
      properties:
        __typename:
          type: string
        chainPositions:
          description: A list of all the chain positions of this chain in the format.
          items:
            $ref: '#/components/schemas/ProteinFormatChainPosition'
          type: array
        domains:
          description: The domains that compose this chain.
          items:
            $ref: '#/components/schemas/ProteinFormatDomain'
          type: array
        label:
          description: 'A human-readable label for the chain, such as ''Heavy'' or ''Light 1''.

            Chains are labeled with an index only when multiple distinct chains of the same type exist.

            These labels are unique among distinct chains in a format.'
          type: string
        type:
          description: The type of the chain.
          enum:
          - HEAVY
          - LIGHT
          - NONE
          - ALPHA
          - BETA
          - JOINING
          type: string
      type: object
    AsyncTaskLink:
      properties:
        pollingUri:
          format: uri
          type: string
        taskId:
          type: string
      type: object
    UpdateProteinFormatInputWithPathParams:
      additionalProperties: false
      properties:
        archiveReason:
          type: string
        archived:
          type: boolean
        id:
          type: string
        name:
          description: The display name of the protein format.
          type: string
      required:
      - id
      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
    UpdateProteinFormatInput:
      additionalProperties: false
      properties:
        archiveReason:
          type: string
        archived:
          type: boolean
        name:
          description: The display name of the protein format.
          type: string
      type: object
    PrincipalRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    CreateProteinFormatInput:
      additionalProperties: false
      example:
        displayName: IgG-Fab format
        veritasName: IgG-Fab
      properties:
        displayName:
          description: The display name of the protein format. If not provided, the VERITAS name will be used.
          type: string
        veritasName:
          description: The VERITAS name of the protein format, used to build the structure and visualization.
          type: string
      required:
      - veritasName
      type: object
    ProteinFormatPaginatedList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/ProteinFormat'
          type: array
        nextToken:
          type: string
      type: object
    ProteinFormatDomain:
      description: 'A domain in a protein format, representing the slot where an amino acid sequence can be used in an entity

        of this format. Domains are uniquely identified by their label in the format.'
      properties:
        __typename:
          type: string
        domainPositions:
          description: A list of all the domain positions of this domain in the format.
          items:
            $ref: '#/components/schemas/ProteinFormatDomainPosition'
          type: array
        label:
          description: A human-readable label for the domain, uniquely identifying the domain within the format.
          type: string
        optional:
          description: Whether this domain is optional in the format. If true, entities of this format may not have this domain.
          type: boolean
        type:
          description: The type of the domain (e.g., VH, VL, CH1).
          enum:
          - VL
          - CL
          - VH
          - VHH
          - CH1
          - CH2
          - CH3
          - CH4
          - J
          - H
          - L
          - VA
          - CA
          - VB
          - CB
          - VG
          - CG
          - VD
          - CD
          - F
          - ELEMENT
          type: string
      type: object
    ProteinFormatDomainPosition:
      description: 'Defines a domain position within a1 `ProteinFormat`, specifying the domain type and identity of each

        physical domain in the protein format. Each domain position has a unique ref identifier used

        to construct HELM notation for complex polymer structures. Domain positions are grouped into ProteinFormatDomains,

        and each group can be uniquely identified by its label, and will be a single amino acid sequence entity in proteins

        of this format.'
      properties:
        __typename:
          type: string
        optional:
          description: Whether this domain is optional in the format. If true, entities of this format may not have this domain.
          type: boolean
        ref:
          description: 'A unique identifier for a physical component (chain or domain) in a protein format.

            This is used to form a HELM reference that is used in the protein''s complex polymer structure.'
          type: integer
        type:
          description: Type of the domain
          enum:
          - VL
          - CL
          - VH
          - VHH
          - CH1
          - CH2
          - CH3
          - CH4
          - J
          - H
          - L
          - VA
          - CA
          - VB
          - CB
          - VG
          - CG
          - VD
          - CD
          - F
          - ELEMENT
          type: string
      type: object
    GeneralError:
      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
    ProteinFormat:
      description: 'A ProteinFormat defines the structural template for a class of proteins, specifying the

        arrangement of chains and domains. Formats can be built-in (e.g., IgG1, Fab, scFv) or

        custom-defined by users.'
      properties:
        __typename:
          type: string
        archiveDatetime:
          format: datetime
          type:
          - 'null'
          - string
        archiveReason:
          type:
          - 'null'
          - string
        archiveUser:
          oneOf:
          - $ref: '#/components/schemas/PrincipalRef'
          - type: 'null'
        archived:
          type: boolean
        builtIn:
          description: 'Whether this is an out-of-the-box Benchling-provided format. These formats come pre-loaded and cannot be

            modified or deleted by users.'
          type: boolean
        chainPositions:
          description: Format chains positions include all physical instances of each chain in a protein of this format.
          items:
            $ref: '#/components/schemas/ProteinFormatChainPosition'
          type: array
        chains:
          description: 'The chains of protein entities of this format. Each chain can have multiple chain sites, representing

            multiple physical instances of the same chain.'
          items:
            $ref: '#/components/schemas/ProteinFormatChain'
          type: array
        domainPositions:
          description: 'Format domain positions include all physical instances of each domain in a protein of this

            format.'
          items:
            $ref: '#/components/schemas/ProteinFormatDomainPosition'
          type: array
        domains:
          description: 'The domains of protein entities of this format. Each domain can have multiple domain sites, representing

            multiple physical instances of the same domain.'
          items:
            $ref: '#/components/schemas/ProteinFormatDomain'
          type: array
        id:
          type: string
        name:
          description: The display name of the protein format.
          type: string
        originalVeritas:
          description: The VERITAS string used to create the format.
          type:
          - 'null'
          - string
      type: object
  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: /oauth/token
      type: oauth2