Benchling Protein API

openapi: 3.2.0
info:
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Benchling Protein API
  version: 2.0.0
  description: 'A Protein is a complex biomolecule entity in Benchling representing immunoglobulins or

    related therapeutic proteins like T-cell receptors. Proteins are defined by an

    `ProteinFormat` that specifies their structural organization, with actual sequences

    provided in domains (see `ProteinDomain`) and chains (see `ProteinChain`). Proteins support versioning

    through history/fullHistory, allowing tracking of structural changes over time. As registry entities,

    proteins can have schemas with custom fields, belong to projects and folders, and be linked to studies.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A Protein is a complex biomolecule entity in Benchling representing immunoglobulins or

    related therapeutic proteins like T-cell receptors. Proteins are defined by an

    `ProteinFormat` that specifies their structural organization, with actual sequences

    provided in domains (see `ProteinDomain`) and chains (see `ProteinChain`). Proteins support versioning

    through history/fullHistory, allowing tracking of structural changes over time. As registry entities,

    proteins can have schemas with custom fields, belong to projects and folders, and be linked to studies.'
  name: Protein
  x-bnch-core-type: Protein
  x-bnch-organization: Benchling
paths:
  /protein:
    post:
      description: Create Protein.
      operationId: Protein.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/CreateProteinInput'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Protein'
          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 Protein
      tags:
      - Protein
      x-bnch-rate-limit-tier: 4
  /protein/items:
    get:
      description: List Protein items.
      operationId: Protein.List
      parameters:
      - $ref: '#/components/parameters/archiveReason.anyOf'
      - $ref: '#/components/parameters/archived.anyOf'
      - $ref: '#/components/parameters/authors.anyOf'
      - $ref: '#/components/parameters/createdAt.gt'
      - $ref: '#/components/parameters/createdAt.gte'
      - $ref: '#/components/parameters/createdAt.lt'
      - $ref: '#/components/parameters/createdAt.lte'
      - $ref: '#/components/parameters/creator.anyOf'
      - $ref: '#/components/parameters/fieldset.anyOf'
      - $ref: '#/components/parameters/id.anyOf'
      - $ref: '#/components/parameters/mentionedIn.anyOf'
      - $ref: '#/components/parameters/modifiedAt.gt'
      - $ref: '#/components/parameters/modifiedAt.gte'
      - $ref: '#/components/parameters/modifiedAt.lt'
      - $ref: '#/components/parameters/modifiedAt.lte'
      - $ref: '#/components/parameters/name.anyOf'
      - $ref: '#/components/parameters/name.anyOf.caseSensitive'
      - $ref: '#/components/parameters/nextToken'
      - $ref: '#/components/parameters/omit'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/project.eq'
      - $ref: '#/components/parameters/registry.eq'
      - $ref: '#/components/parameters/returning'
      - $ref: '#/components/parameters/schema.anyOf'
      - $ref: '#/components/parameters/schema.eq'
      - $ref: '#/components/parameters/systemCategory.anyOf'
      - 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/ProteinPaginatedList'
          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 Protein items
      tags:
      - Protein
      x-bnch-rate-limit-tier: 4
  /protein/{protein_id}:
    get:
      description: Get a single Protein by ID.
      operationId: Protein.Get
      parameters:
      - description: ID of the Protein.
        in: path
        name: protein_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/Protein'
          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 Protein by ID
      tags:
      - Protein
      x-bnch-rate-limit-tier: 5
    patch:
      description: Update Protein.
      operationId: Protein.Update
      parameters:
      - description: ID of the Protein.
        in: path
        name: protein_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/UpdateProteinInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Protein'
          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 Protein
      tags:
      - Protein
      x-bnch-rate-limit-tier: 4
  /protein/{protein_id}/authors/items:
    get:
      description: List Principal items.
      operationId: Protein.authors.List
      parameters:
      - description: ID of the Protein.
        in: path
        name: protein_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/PrincipalUnpaginatedList'
          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 Principal items
      tags:
      - Protein
      x-bnch-rate-limit-tier: 4
  /protein/{protein_id}/full-history/items:
    get:
      description: List ProteinVersion items.
      operationId: Protein.fullHistory.List
      parameters:
      - description: ID of the Protein.
        in: path
        name: protein_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/ProteinVersionUnpaginatedList'
          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 ProteinVersion items
      tags:
      - Protein
      x-bnch-rate-limit-tier: 4
  /protein/{protein_id}/history/items:
    get:
      description: List ProteinVersion items.
      operationId: Protein.history.List
      parameters:
      - description: ID of the Protein.
        in: path
        name: protein_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/ProteinVersionUnpaginatedList'
          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 ProteinVersion items
      tags:
      - Protein
      x-bnch-rate-limit-tier: 4
  /protein:batch-create:
    post:
      description: Batch create Protein synchronously in one transaction. Maximum 25 items per request.
      operationId: Protein.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/CreateProteinInput'
                  maxItems: 25
                  minItems: 1
                  type: array
              required:
              - items
              type: object
      responses:
        '201':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/Protein'
                    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 Protein
      tags:
      - Protein
      x-bnch-rate-limit-tier: 3
  /protein:batch-update:
    patch:
      description: Batch update Protein synchronously in one transaction. Maximum 25 items per request.
      operationId: Protein.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/UpdateProteinInputWithPathParams'
                  maxItems: 25
                  minItems: 1
                  type: array
              required:
              - items
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/Protein'
                    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 Protein
      tags:
      - Protein
      x-bnch-rate-limit-tier: 3
  /protein:bulk-create:
    post:
      description: Bulk create Protein.
      operationId: Protein.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 Protein
      tags:
      - Protein
      x-bnch-rate-limit-tier: 2
  /protein:bulk-update:
    patch:
      description: Bulk update Protein.
      operationId: Protein.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 Protein
      tags:
      - Protein
      x-bnch-rate-limit-tier: 2
  /proteins:bulk-create-and-register-proteins-and-components:
    post:
      description: Create and register proteins and their component parts (domains, chains, and variable pairs)
      operationId: ProteinsAndComponents.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:
              additionalProperties: false
              properties:
                entryId:
                  description: 'The ID of the notebook entry into which the creation results will be embedded upon completion.

                    If omitted, no results are written to a notebook entry.

                    '
                  example: etr_8eTVGFUm2T
                  type: string
                folderId:
                  description: The ID of the folder in which the new entities should be created.
                  example: lib_lKsxK6
                  type: string
                germlineConfigs:
                  description: 'A list of germline configs indicating the germline with which to annotate each domain key.

                    This applies to all rows in the request.

                    '
                  items:
                    additionalProperties: false
                    properties:
                      domainKey:
                        additionalProperties: false
                        properties:
                          label:
                            description: The domain label (e.g., "VH", "VL").
                            example: VH
                            type: string
                        required:
                        - label
                        type: object
                      germlineId:
                        description: API ID of the germline to use for this domain.
                        example: grmln_abc123
                        type: string
                    required:
                    - domainKey
                    - germlineId
                    type: object
                  nullable: true
                  type: array
                newComponentConfig:
                  additionalProperties: false
                  description: 'Schema IDs for new component entities created during this request.

                    Applies to all rows in the request.

                    '
                  properties:
                    aaPairSchemaId:
                      description: 'Schema ID for creating Amino Acid variable pair entities for this request.

                        '
                      example: ts_aapair012
                      type: string
                    dnaChainSchemaId:
                      description: 'Schema ID for DNA chain sequences created for this request.

                        Required if there are DNA inputs.

                        '
                      example: ts_dnachain456
                      nullable: true
                      type: string
                    dnaDomainSchemaId:
                      description: 'Schema ID for DNA domain sequences created for this request.

                        Required if there are DNA inputs.

                        '
                      example: ts_dnadomain123
                      nullable: true
                      type: string
                    dnaPairSchemaId:
                      description: 'Schema ID for creating DNA variable pair entities for this request.

                        Required if there are DNA inputs.

                        '
                      example: ts_dnapair789
                      nullable: true
                      type: string
                  required:
                  - aaPairSchemaId
                  type: object
                proteinCreateInputs:
                  items:
                    additionalProperties: false
                    anyOf:
                    - required:
                      - domains
                    - required:
                      - chains
                    description: 'Describes one complete protein and optionally some of the DNA that encodes for it.


                      The input does not necessarily need to contain every domain and every chain

                      defined in the associated proteinSchema, and users of this API are welcome to leave

                      many of them out as long as they meet the following constraint:


                      For every amino acid chain type defined in the proteinSchema, either

                      a) it must occur in the chains array

                      or

                      b) each of its constituent domain types must occur in the domains array, or occur as a component

                      of one of the provided variablePairs.


                      Chains that are not provided will be derived from their constituent domains.

                      Domains that are not provided will be annotated and decomposed based on an analysis of the sequence of the

                      chains containing them.

                      '
                    properties:
                      chains:
                        items:
                          additionalProperties: false
                          anyOf:
                          - required:
                            - chainKey
                            - dnaComponent
                          - required:
                            - chainKey
                            - aaComponent
                          description: 'Defines an entity to represent the amino acid residues for one amino acid chain of the protein.

                            Optionally also defines one entity to represent the associated DNA.

                            If only dnaComponent is provided, the amino acid residues will be derived from it by translation.

                            If both dnaComponent and aaComponent are provided, the DNA bases must translate to the Amino Acid residues.

                            '
                          properties:
                            aaComponent:
                              anyOf:
                              - additionalProperties: false
                                properties:
                                  aaSequenceId:
                                    description: API ID of an existing AA sequence.
                                    example: prtn_uIKU1o
                                    type: string
                                  type:
                                    enum:
                                    - EXISTING
                                    example: EXISTING
                                    type: string
                                required:
                                - type
                                - aaSequenceId
                                type: object
                              - additionalProperties: false
                                properties:
                                  residues:
                                    description: The amino acid residues for the new sequence to be created.
                                    example: MEVQLVESGGGLVQPGGSLRLSCAASGF
                                    type: string
                                  type:
                                    enum:
                                    - NEW
                                    example: NEW
                                    type: string
                                required:
                                - type
                                - residues
                                type: object
                            chainKey:
                              additionalProperties: false
                              properties:
                                label:
                                  example: Heavy
                                  type: string
                              required:
                              - label
                              type: object
                            dnaComponent:
                              anyOf:
                              - additionalProperties: false
                                properties:
                                  dnaSequenceId:
                                    description: API ID of an existing DNA sequence.
                                    example: seq_sX1bVB
                                    type: string
                                  type:
                                    enum:
                                    - EXISTING
                                    example: EXISTING
                                    type: string
                                required:
                                - type
                                - dnaSequenceId
                                type: object
                              - additionalProperties: false
                                properties:
                                  bases:
                                    description: The DNA bases for the new sequence to be created.
                                    example: ATGCATGC
                                    type: string
                                  type:
                                    enum:
                                    - NEW
                                    example: NEW
                                    type: string
                                required:
                                - type
                                - bases
                                type: object
                          type: object
                        type: array
                      domains:
                        items:
                          additionalProperties: false
                          anyOf:
                          - required:
                            - domainKey
                            - dnaComponent
                          - required:
                            - domainKey
                            - aaComponent
                          description: 'Defines an entity to represent the amino acid residues for one domain of the protein.

                            Optionally also defines one entity to represent the associated DNA.

                            If only dnaComponent is provided, the amino acid residues will be derived from it by translation.

                            If both dnaComponent and aaComponent are provided, the DNA bases must translate to the Amino Acid residues.

                            '
                          properties:
                            aaComponent:
                              anyOf:
                              - additionalProperties: false
                                properties:
                                  aaSequenceId:
                                    description: API ID of an existing AA sequence entity.
                                    example: prtn_uIKU1o
                                    type: string
                                  type:
                                    enum:
                                    - EXISTING
                                    example: EXISTING
                                    type: string
                                required:
                                - type
                                - aaSequenceId
                                type: object
                              - additionalProperties: false
                                properties:
                                  residues:
                                    description: The amino acid residues to use for the new Amino Acid sequence entity.
                                    example: MEVQLVESGGGLVQPGGSLRLSCAASGF
                                    type: string
                                  type:
                                    enum:
                                    - NEW
                                    example: NEW
                                    type: string
                                required:
                                - type
                                - residues
                                type: object
                            dnaComponent:
                              anyOf:
                              - additionalProperties: false
                                properties:
                                  dnaSequenceId:
                                    description: API ID of an existing DNA sequence entity.
                                    example: seq_sX1bVB
                                    type: string
                                  type:
                                    enum:
                                    - EXISTING
                                    example: EXISTING
                                    type: string
                                required:
                                - type
                                - dnaSequenceId
                                type: object
                              - additionalProperties: false
                                properties:
                                  bases:
                                    description: The DNA bases to use for the new DNA sequence entity.
                                    example: ATGCATGCC
                                    type: string
                                  type:
                                    enum:
                                    - NEW
                                    example: NEW
                                    type: string
                                required:
                                - type
                                - bases
                                type: object
                            domainKey:
                              additionalProperties: false
                              properties:
                                label:
                                  description: The domain label (e.g., "VH", "CH1(Heavy)", "VLkappa").
                                  example: CH1(Heavy)
                                  type: string
                              required:
                              - label
                              type: object
                          type: object
                        type: array
                      variablePairs:
                        description: 'A list of variable domain pair inputs (e.g., VH+VL for antibodies, VA+VB for TCRs).

                          Each pair is identified by its two constituent domain keys.

                          '
                        items:
                          additionalProperties: false
                          anyOf:
                          - required:
                            - pairKey
                            - dnaPairId
                          - required:
                            - pairKey
                            - aaPairId
                          properties:
                            aaPairId:
                              description: API ID of an existing AA variable pair entity.
                              example: bfi_def456
                              type: string
                            dnaPairId:
                              description: API ID of an existing DNA variable pair entity.
                              example: bfi_abc123
                              type: string
                            pairKey:
                              additionalProperties: false
                              description: 'Identifies the variable domain pair by its two constituent domain keys.

                                ''vhVaVg'' covers VH (antibody), VA (TCR alpha/delta), or V

# --- truncated at 32 KB (108 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/benchling/refs/heads/main/openapi/benchling-protein-api-openapi.yml