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 VG (TCR gamma) domains. ''vlVbVd'' covers VL (antibody), VB (TCR beta), or VD (TCR delta) domains. ' properties: vhVaVg: additionalProperties: false properties: label: description: The domain label of the VH, VA, or VG domain in this pair. example: VH type: string required: - label type: object vlVbVd: additionalProperties: false properties: label: description: The domain label of the VL, VB, or VD domain in this pair. example: VL type: string required: - label type: object required: - vhVaVg - vlVbVd type: object type: object nullable: true type: array type: object minItems: 1 type: array proteinSchemaId: description: The schema ID for the protein entity type. example: ts_XEUrLw type: string translationParameters: additionalProperties: false description: 'The translation parameters to use when creating AA sequences. Required if the request contains DNA sequences. May be omitted if the request contains only AA sequences. ' properties: geneticCode: description: The codon table to use to translate DNA sequences to AA sequences. enum: - STANDARD - VERTEBRATE_MITOCHONDRIAL - YEAST_MITOCHONDRIAL - MOLD_MITOCHONDRIAL - INVERTEBRATE_MITOCHONDRIAL - CILIATE_NUCLEAR - ECHINODERM_MITOCHONDRIAL - EUPLOTID_NUCLEAR - BACTERIAL_ARCHAEAL - ALTERNATIVE_YEAST_NUCLEAR - ASCIDIAN_MITOCHONDRIAL - ALTERNATIVE_FLATWORM_MITOCHONDRIAL - BLEPHARISMA_NUCLEAR - CHLOROPHYCEAN_MITOCHONDRIAL - TREMATODE_MITOCHONDRIAL - SCENEDESMUS_OBLIQUUS_MITOCHONDRIAL - THRAUSTOCHYTRIUM_MITOCHONDRIAL - PTEROBRANCHIA_MITOCHONDRIAL - CANDIDATE_DIVISION_SR1 type: string required: - geneticCode type: object required: - folderId - proteinSchemaId - newComponentConfig - proteinCreateInputs type: object description: 'Create and register proteins along with their component domains, chains, and variable pairs. Does not create plasmids. **Optional/Required Inputs** Any components that are not provided in the input will be derived from other input components when possible. For example, AA domains are not necessary if DNA domains are provided. See the documentation on the proteinCreateInputs parameter for more detail. Here are some example ways to provide the inputs: - provide all domains as DNA - provide all domains as AA - provide constant domains as AA and variable domains using variable pairs **Scale** A single call to this API may include up to: - 1,000 antibodies - 4,000 AA chains - 4,000 DNA chains - 14,000 AA domains - 14,000 DNA domains - 2,000 DNA pairs - 2,000 AA pairs **Large requests may take several hours to complete.** When results are ready, they''ll be aggregated into a Benchling.Dataset object, and added to the folder and entry referenced in the input. **Error Handling and Partial Success** All inputs are validated before any registrations begin. If any input fails validation, no proteins are registered. In rare cases (e.g. concurrent manual data changes during a running task), a partial success is possible. ' responses: '202': content: application/json: schema: properties: pollingUri: description: A URL to poll for the status of the task. example: https://tenant.com/api/v3/tasks/bulk-create-and-register-proteins-and-components/cprotjob:ana_fhlbqd format: uri type: string taskId: example: cprotjob:ana_fhlbqd type: string required: - taskId - pollingUri type: object description: Job status details '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 and register proteins and components tags: - Protein x-bnch-rate-limit-tier: 2 /tasks/bulk-create-and-register-proteins-and-components/{task_id}: get: description: 'Get the current status of a bulk-create-and-register-proteins-and-components task. When a job reaches a `COMPLETED` status, you can call the `GET /tasks/bulk-create-and-register-proteins-and-components/{task_id}/results` endpoint to fetch task results and errors. Task IDs for this endpoint remain queryable for 14 days after the job is created. After that TTL expires, this endpoint returns 404. Retrieve any status and results you need before the task ID expires. ' operationId: BulkCreateAndRegisterProteinsAndComponentsTask.Get parameters: - in: path name: task_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: properties: result: properties: hasErrors: example: false type: boolean hasSuccess: example: true type: boolean required: - hasSuccess - hasErrors type: object status: description: "The current status of the task.\n- NOT_STARTED: Task has been created but not yet started.\n- IN_PROGRESS: Task is currently running.\n- COMPLETED: Task finished. Check 'result.hasErrors' to determine if there were validation errors.\n- FAILED: Task encountered an internal error (system failure). This is distinct from user-facing validation errors,\n which result in a COMPLETED status with hasErrors=true.\n" enum: - NOT_STARTED - IN_PROGRESS - COMPLETED - FAILED example: IN_PROGRESS type: string taskId: example: cprotjob:ana_fhlbqd type: string required: - taskId - status - result type: object description: Job status details '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 bulk-create-and-register-proteins-and-components task status tags: - Protein x-bnch-rate-limit-tier: 5 /tasks/bulk-create-and-register-proteins-and-components/{task_id}/results: get: description: "Get the results of a completed bulk-create-and-register-proteins-and-components task.\n\nThis endpoint returns an identifier for the output dataset, plus an optional\npre-signed URL to download the errors file if any inputs failed validation.\n\nTask IDs for this endpoint remain queryable for 14 days after the\njob is created.\nAfter that TTL expires, this endpoint returns 404. Retrieve the dataset\nID and any errors file URL you need before the task ID expires.\n\n**Partial Success**: A job can complete with both successful and failed inputs. Always check\n`errorsFileUrl` even when `datasetId` is present, since some inputs may have been rejected\nwhile others were created successfully.\n\nBehavior:\n- Returns 400 unless the task has a COMPLETED status. While a task is running\n you can poll the\n `GET /tasks/bulk-create-and-register-proteins-and-components/{task_id}`\n endpoint first and only call this endpoint once\n `status == \"COMPLETED\"`. If the status becomes FAILED, this endpoint\n will always return 400.\n- If the task is in a COMPLETED status, returns parameters you can\n use to fetch output and error data. See the descriptions of the output\n parameters for more detail.\n" operationId: BulkCreateAndRegisterProteinsAndComponentsResults.Get parameters: - in: path name: task_id required: true schema: example: cprotjob:ana_fhlbqd 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: properties: datasetId: description: "If no proteins were registered, this parameter is absent.\nOtherwise, `datasetId` identifies a Dataset object with the results data.\n\nUse this id with the Datasets API to look up the dataset and fetch\nits rows. This dataset will be the same one displayed in the Benchling UI\nand referenced in emails about this task.\n\nDataset Columns\n- The results dataset will have an `input` column giving the index\n of the input protein data associated to this results row.\n- It will have a `protein` column giving the api id\n of the protein that was registered for that input.\n- It will have a `{label}_aa` and optionally a `{label}_dna` column\n for each domain label in the format. The DNA column will only be\n present if the job registered DNA sequence entities for that format.\n- It will have similar `{label}_dna` and `{label}_aa` columns for\n chains that it registered.\n- It will also have `{label1}_{label2}_pair_dna` and\n `{label1}_{label2}_pair_aa` columns for any registered DNA and AA pairs.\n" example: dataset_abc123 type: string errorsFileUrl: description: 'If all inputs were registered successfully, this parameter is absent. Otherwise, it''s a pre-signed S3 URL for downloading the errors CSV. This CSV will have an `Input #` column giving the index of the input to the job associated with one particular protein that failed to be registered. The `Error Message` column gives a description of the error. This file may also contain additional columns for any sequence data that the job attempted to use when it failed to register this particular protein. Those columns will follow the same naming scheme as described above for the Dataset output. ' example: https://bucket.s3.amazonaws.com/atsk_123/download?X-Amz-Signature=abc123 format: uri type: string taskId: example: cprotjob:ana_fhlbqd type: string required: - taskId type: object description: Task results '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 bulk-create-and-register-proteins-and-components task results tags: - Protein x-bnch-rate-limit-tier: 5 components: 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 ProteinFormatRef: properties: __typename: type: string id: format: api_id type: string type: object ProjectRef: properties: __typename: type: string id: format: api_id type: string type: object AppInstallation: description: 'Represents an installed Benchling App on a tenant, created from an `AppDefinitionVersion`. App installations store tenant-specific configuration values and feature bindings. As a Principal, app installations can be attributed as actors for API operations and auditing.' properties: __typename: type: string archiveReason: type: - 'null' - string archived: type: boolean configurationValues: format: uri type: string createdAt: format: datetime type: - 'null' - string creator: oneOf: - $ref: '#/components/schemas/PrincipalRef' - type: 'null' featureValues: items: $ref: '#/components/schemas/AssayRunFeatureValue' type: array id: type: string modifiedAt: format: datetime type: - 'null' - string name: type: string type: object CustomField: description: 'A name-value pair for storing additional metadata on objects that support custom fields. CustomFields provide a flexible way to attach arbitrary string data to entities, containers, datasets, and other Benchling objects without modifying their schemas. Objects that can have custom fields implement the HasCustomFields interface. Unlike schema-defined fields, custom fields are not validated against a schema and can be freely added or modified.' properties: __typename: type: string name: type: - 'null' - string value: type: - 'null' - string type: object User: description: 'Represents a human user in Benchling who can log in, perform actions, and own data. Users belong to one or more Organizations and may be members of Teams within those organizations. As an Owner, users can own Projects, Folders, and other resources. As a Principal, users can be assigned as reviewers, authors, or collaborators on various items. Users have attributes like email and username for identification. Users are distinct from `ServicePrincipal`, which represents non-human service accounts used for integrations.' properties: __typename: type: string createdAt: format: datetime type: string email: type: string id: type: string lastSeen: format: datetime type: - 'null' - string modifiedAt: format: datetime type: string name: type: - 'null' - string status: enum: - ACTIVE - SUSPENDED type: string username: type: string type: object SchemaFieldValue: description: 'Represents a field value on a schematized object, pairing a `fieldDefinition` (describing the field''s type and constraints) with its actual `value` (a `BenchlingValue` such as text, number, date, or link to another object). The value may be null if no value has been set. Used within the `schemaFields` collection on objects that implement `HasSchema` to provide access to all custom field values defined by the object''s schema.' properties: __typename: type: string fieldDefinition: $ref: '#/components/schemas/SchemaFieldDefinitionRef' id: type: string linkedEntityId: type: - 'null' - string value: description: Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue, ArrayValue oneOf: - anyOf: - $ref: '#/components/schemas/BooleanValue' - $ref: '#/components/schemas/DateTimeValue' - $ref: '#/components/schemas/DateValue' - $ref: '#/components/schemas/DecimalValue' - $ref: '#/components/schemas/IntegerValue' - $ref: '#/components/schemas/JsonValue' - $ref: '#/components/schemas/ObjectLinkValue' - $ref: '#/components/schemas/ObjectLinkListValue' - $ref: '#/components/schemas/TextAndUrlValue' - $ref: '#/components/schemas/TextValue' - $ref: '#/components/schemas/ArrayValue' discriminator: propertyName: __typename - type: 'null' type: object AppConfigWorkflowTaskSchemaOutput: description: Defines the output field structure for a workflow task schema configuration. properties: __typename: type: string fieldDefinitions: oneOf: - items: $ref: '#/components/schemas/AppConfigFieldDefinition' type: array - type: 'null' type: object ResourceAppConfigSpec: description: 'Specifies that an app configuration field should reference a Benchling object instance. The type field identifies the kind of object required, matching the BenchlingAppType values used in app manifests (e.g. dna_sequence, folder, registry). Covers all instance reference types with no additional spec constraints beyond requiredConfig. For schema references use SchemaAppConfigSpec or EntitySchemaAppConfigSpec.' properties: __typename: type: string requiredConfig: type: - 'null' - boolean type: enum: - BOX_SCHEMA - CONTAINER_SCHEMA - ENTRY_SCHEMA - LEGACY_REQUEST_SCHEMA - LOCATION_SCHEMA - PLATE_SCHEMA - RESULT_SCHEMA - RUN_SCHEMA - WORKFLOW_TASK_SCHEMA - AA_SEQUENCE - ASSAY_RESULT - ASSAY_RUN - AUTOMATION_INPUT_GENERATOR - AUTOMATION_OUTPUT_PROCESSOR - BLOB - BOX - CONTAINER - CUSTOM_ENTITY - DNA_ALIGNMENT - DNA_OLIGO - DNA_SEQUENCE - DROPDOWN - DROPDOWN_OPTION - ENTRY - FIELD - FOLDER - LEGACY_REQUEST - LOCATION - MIXTURE - MOLECULE - PLATE - PROJECT - REGISTRY - RNA_OLIGO - RNA_SEQUENCE - WORKFLOW_TASK_STATUS - WORKLIST - null type: - 'null' - string type: object AaSequenceRef: properties: __typename: type: string id: format: api_id type: string type: object DateTimeValue: description: A type that represents datetime values. properties: __typename: type: string value: description: The datetime value with UTC as the timezone. format: datetime type: string type: object RegistrationOrigin: description: 'Captures the provenance of an entity''s registration into the registry. The `originEntry` links to the `DocumentLike` (typically an entry or notebook) from which the entity was registered, providing traceability back to the original experimental context. The `registeredAt` timestamp records when the registration occurred. This information helps scientists understand where registered entities came from and when they were added to the registry.' properties: __typename: type: string originEntry: oneOf: - $ref: '#/components/schemas/DocumentLikeRef' - type: 'null' registeredAt: format: datetime type: - 'null' - string type: object FolderRef: properties: __typename: type: string id: format: api_id type: string type: object FloatAppConfigSpec: description: Specifies that an app configuration field should accept a floating-point number. properties: __typename: type: string enum: description: Optional enum constraint — if present, the value must be one of these floats. oneOf: - items: type: number type: array - type: 'null' requiredConfig: type: - 'null' - boolean type: object WorkflowTaskSchemaAppConfigSpec: description: 'Specifies that an app configuration field should reference a workflow task schema. Kept separate from SchemaAppConfigSpec because it supports output field definitions.' properties: __typename: type: string fieldDefinitions: oneOf: - items: $ref: '#/components/schemas/AppConfigFieldDefinition' type: array - type: 'null' output: description: Output field definitions for the workflow task schema. oneOf: - $ref: '#/components/schemas/AppConfigWorkflowTaskSchemaOutput' - type: 'null' requiredConfig: type: - 'null' - boolean type: object EntitySchemaAppConfigSpec: description: 'Specifies that an app configuration field should reference an entity schema. Kept separate from SchemaAppConfigSpec because it carries a subtype constraint.' properties: __typename: type: string fieldDefinitions: oneOf: - items: $ref: '#/components/schemas/AppConfigFieldDefinition' type: array - type: 'null' requiredConfig: type: - 'null' - boolean subtype: description: 'Optional subtype constraint — if present, the referenced schema must be of this entity type (e.g. DNA_SEQUENCE, AA_SEQUENCE).' enum: - AA_SEQUENCE - CUSTOM_ENTITY - DNA_OLIGO - DNA_SEQUENCE - MIXTURE - MOLECULE - RNA_OLIGO - RNA_SEQUENCE - null type: - 'null' - string type: object AppConfigFieldDefinition: description: 'Defines a field within an app configuration that references schema fields. Specifies the field name, type, whether it accepts multiple values, and whether it is required.' properties: __typename: type: string description: type: - 'null' - string isMulti: description: Whether the field must be multi-valued — null means either true or false is acceptable. type: - 'null' - boolean isRequired: description: Whether the field must be required — null means either true or false is acceptable. type: - 'null' - boolean name: type: string requiredConfig: type: - 'null' - boolean type: description: Type constraint for the field — null means any type is acceptable. enum: - DNA_SEQUENCE_LINK - AA_SEQUENCE_LINK - CUSTOM_ENTITY_LINK - ENTITY_LINK - MIXTURE_LINK - MOLECULE_LINK - DROPDOWN - PART_LINK - AA_PART_LINK - TRANSLATION_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 - null type: - 'null' - string type: object JsonValue: description: A type that represents JSON values. properties: __typename: type: string value: description: The JSON value. type: object type: object TextAndUrlValue: description: A type that represents text (string) values with an associated URL. properties: __typename: type: string url: description: The URL associated with the value. Please use `TextValue` if you don't want a URL. type: string value: description: The text value. It may or may not be an empty string. type: string type: object SchemaAppConfigSpec: description: 'Specifies that an app configuration field should reference one of the schema types that share a common structure: container_schema, plate_schema, location_schema, box_schema, run_schema, result_schema, legacy_request_schema, or entry_schema. The type field identifies which schema kind is required. For entity_schema use EntitySchemaAppConfigSpec; for workflow_task_schema use WorkflowTaskSchemaAppConfigSpec.' properties: __typename: type: string fieldDefinitions: oneOf: - items: $ref: '#/components/schemas/AppConfigFieldDefinition' type: array - type: 'null' requiredConfig: type: - 'null' - boolean type: enum: - BOX_SCHEMA - CONTAINER_SCHEMA - ENTRY_SCHEMA - LEGACY_REQUEST_SCHEMA - LOCATION_SCHEMA - PLATE_SCHEMA - RESULT_SCHEMA - RUN_SCHEMA - WORKFLOW_TASK_SCHEMA - AA_SEQUENCE - ASSAY_RESULT - ASSAY_RUN - AUTOMATION_INPUT_GENERATOR - AUTOMATION_OUTPUT_PROCESSOR - BLOB - BOX - CONTAINER - CUSTOM_ENTITY - DNA_ALIGNMENT - DNA_OLIGO - DNA_SEQUENCE - DROPDOWN - DROPDOWN_OPTION - ENTRY - FIELD - FOLDER - LEGACY_REQUEST - LOCATION - MIXTURE - MOLECULE - PLATE - PROJECT - REGISTRY - RNA_OLIGO - RNA_SEQUENCE - WORKFLOW_TASK_STATUS - WORKLIST - null type: - 'null' - 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 ProteinChain: description: 'Represents a polypeptide chain within an `Protein`, containing the domain composition. Each chain has a computed label derived from the format.' properties: __typename: type: string chainPositions: description: 'Each chain position of this chain in the protein. If a chain has multiplicity > 1, each chain position will be listed here.' items: $ref: '#/components/schemas/ProteinFormatChainPosition' type: array domains: description: Each domain on the chain, ordered according to the format. items: $ref: '#/components/schemas/ProteinDomain' type: array entity: $ref: '#/components/schemas/AaSequenceRef' description: The amino acid sequence entity associated with the chain. label: description: Unique label for the chain, computed from the format. type: string type: description: The type of the chain. enum: - HEAVY - LIGHT - NONE - ALPHA - BETA - JOINING type: string type: object JsonAppConfigSpec: description: Specifies that an app configuration field should accept a JSON value. properties: __typename: type: string requiredConfig: type: - 'null' - boolean type: object AnyType: {} CanvasFeatureSpec: description: 'Defines a canvas feature for a Benchling App, which provides an embedded UI surface within entries or templates. Canvases allow apps to render custom interactive content.' properties: __typename: type: string featureId: type: string locations: oneOf: - items: enum: - ENTRY - ENTRY_TEMPLATE - APP_HOME type: string type: array - type: 'null' name: type: string type: object ObjectLinkValue: description: A type that represents links to other objects. properties: __typename: type: string value: $ref: '#/components/schemas/ObjectRef' description: The object that this value links to, or an Inaccessible object if not found with the current permission set. type: object UpdateProteinInput: additionalProperties: false properties: aliases: items: type: string type: array archiveReason: type: string archived: type: boolean authorIds: items: type: string type: array chains: description: A chain input for each chain on the relevant format. Must be all provided if domains are provided. items: $ref: '#/components/schemas/ProteinChainInput' type: array customFields: additionalProperties: $ref: '#/components/schemas/FieldValueInput' type: object domains: description: A domain input for each domain on the relevant format. If any are provided, all must be provided. items: $ref: '#/components/schemas/ProteinDomainInput' type: array entityRegistryId: type: string folderId: type: string name: type: string namingStrategy: 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 registryId: type: - 'null' - string schemaFields: additionalProperties: $ref: '#/components/schemas/FieldValueInput' type: object schemaId: type: string studyIds: description: Study IDs to add the protein to. items: type: string type: array type: object CreateProteinInput: additionalProperties: false properties: aliases: items: type: string type: array authorIds: items: type: string type: array chains: description: A chain input for each chain on the relevant format. All must be provided. items: $ref: '#/components/schemas/ProteinChainInput' type: array customFields: additionalProperties: $ref: '#/components/schemas/FieldValueInput' type: object domains: description: A domain input for each domain on the relevant format. All must be provided. items: $ref: '#/components/schemas/ProteinDomainInput' type: array entityRegistryId: type: string folderId: type: string name: type: string namingStrategy: 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 registryId: type: - 'null' - string schemaFields: additionalProperties: $ref: '#/components/schemas/FieldValueInput' type: object schemaId: description: The ID of the schema to create the protein in. type: string studyIds: description: Study IDs to add the new protein to. items: type: string type: array required: - folderId - name - schemaId - domains - chains 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 DecimalValue: description: A type that represents decimal value as strings. properties: __typename: type: string numericValue: deprecated: true description: Deprecated. The float representation of the decimal value. type: - 'null' - number value: description: The decimal value in a string representation type: - 'null' - string type: object EntitySchemaRef: properties: __typename: type: string id: format: api_id type: string type: object ProteinDomain: description: 'Represents a domain within an `Protein`, containing the actual amino acid sequence for a specific label. Unlike `ProteinFormatDomain` which is a template, `ProteinDomain` is a concrete instance of the domain and links to the underlying amino acid sequence entity.' properties: __typename: type: string domainPositions: description: 'Each domain position of this domain in the protein. If this domain appears multiple times in the physical structure of the protein, each domain position will be listed here.' items: $ref: '#/components/schemas/ProteinFormatDomainPosition' type: array entity: $ref: '#/components/schemas/AaSequenceRef' description: The amino acid sequence entity associated with the domain. label: description: A human-readable label for the domain. type: string type: description: The 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 BooleanAppConfigSpec: description: Specifies that an app configuration field should accept a boolean value. properties: __typename: type: string requiredConfig: type: - 'null' - boolean type: object PrincipalRef: properties: __typename: type: string id: format: api_id type: string type: object TextAppConfigSpec: description: Specifies that an app configuration field should accept a text string. properties: __typename: type: string enum: description: Optional enum constraint — if present, the value must be one of these strings. oneOf: - items: type: string type: array - type: 'null' requiredConfig: type: - 'null' - boolean type: object RegistryRef: properties: __typename: type: string id: format: api_id type: string type: object SchemaFieldDefinitionRef: properties: __typename: type: string id: format: api_id type: string type: object ObjectLinkListValue: description: A type that represents a list of links to other objects. properties: __typename: type: string value: description: The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set. items: $ref: '#/components/schemas/ObjectRef' description: Union of AaSequence, Box, Container, CustomEntity, DnaSequence, DropdownOption, Entry, Location, Mixture, Molecule, Plate, Result, RnaSequence, Run, DnaOligo, RnaOligo type: array type: object LegacyAppInstallation: description: 'Represents a legacy (pre-App Store) Benchling App installation on a tenant. Legacy apps are configured directly with webhook URLs and configuration specs rather than through app definition versions. This type is maintained for backward compatibility with older app integrations. For new apps, see `AppInstallation`.' properties: __typename: type: string archiveReason: type: - 'null' - string archived: type: boolean configurationSpecs: items: $ref: '#/components/schemas/AppConfigOption' type: array configurationValues: format: uri type: string createdAt: format: datetime type: - 'null' - string creator: oneOf: - $ref: '#/components/schemas/PrincipalRef' - type: 'null' description: type: - 'null' - string featureSpecs: items: anyOf: - $ref: '#/components/schemas/CanvasFeatureSpec' - $ref: '#/components/schemas/AssayRunFeatureSpec' - $ref: '#/components/schemas/AppHomepageFeatureSpec' description: Union of CanvasFeatureSpec, AssayRunFeatureSpec, AppHomepageFeatureSpec discriminator: propertyName: __typename type: array featureValues: items: $ref: '#/components/schemas/AssayRunFeatureValue' type: array id: type: string messageSubscriptions: items: $ref: '#/components/schemas/AppMessageSubscription' type: array modifiedAt: format: datetime type: - 'null' - string name: type: string publicKey: type: - 'null' - string versionNumber: type: - 'null' - string webhookUrl: type: - 'null' - string type: object DateAppConfigSpec: description: Specifies that an app configuration field should accept a date value. properties: __typename: type: string requiredConfig: type: - 'null' - boolean type: object AppMessageSubscription: description: 'Represents an app''s subscription to a specific event type, specifying the event type and how notifications should be delivered (see `DeliveryMethod`).' properties: __typename: type: string deliveryMethod: enum: - WEBHOOK - WEBHOOK_INTERNAL type: string type: enum: - V2_BETA_CANVAS_CREATED - V2_CANVAS_CREATED - V2_CANVAS_USER_INTERACTED - V2_CANVAS_INITIALIZED - V2_APP_ACTIVATE_REQUESTED - V2_APP_DEACTIVATED - V2_APP_INSTALLED - V2_BETA_APP_CONFIGURATION_UPDATED - V2_ASSAY_RUN_CREATED - V2_ASSAY_RUN_UPDATED_FIELDS - V2_ENTITY_REGISTERED - V2_ENTRY_CREATED - V2_ENTRY_UPDATED_FIELDS - V2_ENTRY_UPDATED_REVIEW_RECORD - V2_REQUEST_CREATED - V2_REQUEST_UPDATED_FIELDS - V2_REQUEST_UPDATED_STATUS - V2_WORKFLOW_TASK_GROUP_CREATED - V2_WORKFLOW_TASK_GROUP_MAPPING_COMPLETED - V2_WORKFLOW_TASK_GROUP_UPDATED_WATCHERS - V2_WORKFLOW_TASK_CREATED - V2_WORKFLOW_TASK_UPDATED_ASSIGNEE - V2_WORKFLOW_TASK_UPDATED_SCHEDULED_ON - V2_WORKFLOW_TASK_UPDATED_STATUS - V2_WORKFLOW_TASK_UPDATED_FIELDS - V2_WORKFLOW_OUTPUT_CREATED - V2_WORKFLOW_OUTPUT_UPDATED_FIELDS - V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_RUNNING - V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_PENDING - V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_SUCCEEDED - V2_AUTOMATION_FILE_TRANSFORM_UPDATED_STATUS_FAILED - V3_CUSTOM_ENTITY_CREATED - V3_CUSTOM_ENTITY_UPDATED - V3_DNA_OLIGO_CREATED - V3_DNA_OLIGO_UPDATED - V3_DNA_SEQUENCE_CREATED - V3_DNA_SEQUENCE_UPDATED - V3_ENTRY_CREATED - V3_PROJECT_CREATED - V3_PROJECT_UPDATED - V3_RNA_OLIGO_CREATED - V3_RNA_OLIGO_UPDATED - V3_RNA_SEQUENCE_CREATED - V3_RNA_SEQUENCE_UPDATED - V3_RUN_CREATED type: string type: object DateValue: description: A type that represents date values. properties: __typename: type: string value: description: The date value. format: date type: string type: object DropdownAppConfigSpec: description: Specifies that an app configuration field should be a dropdown with predefined options. properties: __typename: type: string options: oneOf: - items: $ref: '#/components/schemas/AppConfigDropdownOption' type: array - type: 'null' requiredConfig: type: - 'null' - boolean type: object ArrayAppConfigSpec: description: Specifies that an app configuration field should accept an array of values. properties: __typename: type: string elementDefinition: description: Defines the named config options allowed within this array and their type constraints. items: $ref: '#/components/schemas/ArrayAppConfigOption' type: array maxElements: description: Maximum number of elements allowed in the array (1-500); null means no maximum. type: - 'null' - integer minElements: description: Minimum number of elements allowed in the array (0-500); null means no minimum. type: - 'null' - integer requiredConfig: type: - 'null' - boolean type: object BooleanValue: description: A type that represents boolean values. properties: __typename: type: string value: description: The boolean value. type: boolean type: object PrincipalUnpaginatedList: additionalProperties: false properties: items: items: $ref: '#/components/schemas/Principal' type: array type: object AssayRunFeatureSpec: description: 'Defines an assay run feature for a Benchling App, allowing the app to process or generate lab automation run data.' properties: __typename: type: string featureId: type: string name: type: string type: object AppHomepageFeatureSpec: description: 'Defines a homepage feature for a Benchling App, providing a dedicated landing page within the Benchling application for the app''s functionality.' properties: __typename: type: string featureId: type: string name: type: string type: object Principal: anyOf: - $ref: '#/components/schemas/AppInstallation' - $ref: '#/components/schemas/LegacyAppInstallation' - $ref: '#/components/schemas/ServicePrincipal' - $ref: '#/components/schemas/User' discriminator: propertyName: __typename type: object ProteinVersion: description: 'A historical snapshot of an `Protein` at a specific point in time, preserving the complete structural state including domains, chains, and HELM notation. Protein versions form a lineage that tracks changes over time. Each version records its creator and creation time. The parent field links to the version this one was derived from. Versions may become out of sync with their constituent entities if underlying sequences change.' properties: __typename: type: string chains: description: The chains and associated amino acid sequences on the protein. items: $ref: '#/components/schemas/ProteinChain' type: array createdAt: format: datetime type: string creator: $ref: '#/components/schemas/PrincipalRef' domains: description: The domains and associated amino acid sequences on the protein. items: $ref: '#/components/schemas/ProteinDomain' type: array format: $ref: '#/components/schemas/ProteinFormatRef' description: The protein format that defines the structure (domains, chains, interactions) for the protein. id: type: string name: type: string outOfSync: description: Indicates if constituent domain or chain entities have changed since the protein was last updated. type: boolean outOfSyncReason: description: Any additional information about why the protein is out of sync. type: - 'null' - string parent: description: The parent version of the protein. oneOf: - $ref: '#/components/schemas/ProteinVersionRef' - type: 'null' 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 DocumentLikeRef: properties: __typename: type: string id: format: api_id type: string type: object AssayRunFeatureValue: description: 'Links an app''s assay run feature to a specific resource (typically a run schema) on a tenant. The featureId identifies the feature from the app definition, and resourceId references the tenant-specific resource it''s bound to.' properties: __typename: type: string featureId: description: Developer-specified feature ID as defined in the app manifest / app definition version type: string resourceId: type: - 'null' - string type: object ArrayAppConfigOption: description: 'A config option nested within an array-type app configuration field. Structurally identical to AppConfigOption — it has a name and a configSpec — but its configSpec accepts the same config types as the top level except nested arrays (see ArrayAppConfigElementSpec).' properties: __typename: type: string configSpec: anyOf: - $ref: '#/components/schemas/BooleanAppConfigSpec' - $ref: '#/components/schemas/IntegerAppConfigSpec' - $ref: '#/components/schemas/FloatAppConfigSpec' - $ref: '#/components/schemas/TextAppConfigSpec' - $ref: '#/components/schemas/SecureTextAppConfigSpec' - $ref: '#/components/schemas/DateAppConfigSpec' - $ref: '#/components/schemas/DateTimeAppConfigSpec' - $ref: '#/components/schemas/JsonAppConfigSpec' - $ref: '#/components/schemas/DropdownAppConfigSpec' - $ref: '#/components/schemas/EntitySchemaAppConfigSpec' - $ref: '#/components/schemas/WorkflowTaskSchemaAppConfigSpec' - $ref: '#/components/schemas/SchemaAppConfigSpec' - $ref: '#/components/schemas/ResourceAppConfigSpec' description: Union of BooleanAppConfigSpec, IntegerAppConfigSpec, FloatAppConfigSpec, TextAppConfigSpec, SecureTextAppConfigSpec, DateAppConfigSpec, DateTimeAppConfigSpec, JsonAppConfigSpec, DropdownAppConfigSpec, EntitySchemaAppConfigSpec, WorkflowTaskSchemaAppConfigSpec, SchemaAppConfigSpec, ResourceAppConfigSpec discriminator: propertyName: __typename description: type: - 'null' - string name: type: string type: object ProteinPaginatedList: additionalProperties: false properties: items: items: $ref: '#/components/schemas/Protein' type: array nextToken: type: string type: object ProteinVersionRef: properties: __typename: type: string id: format: api_id type: string type: object IntegerValue: description: A type that represents integer values. properties: __typename: type: string value: description: The integer value. type: integer type: object ProteinVersionUnpaginatedList: additionalProperties: false properties: items: items: $ref: '#/components/schemas/ProteinVersion' type: array 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 ServicePrincipal: description: 'Represents a non-human identity used for system integrations and automated processes within Benchling. Service principals act as the identity for service accounts that perform actions via APIs or background processes without human intervention. Unlike `User`, which represents a human user, ServicePrincipal is used when an integration or automated system needs to be attributed as the actor for auditing and attribution purposes. Service principals implement the Principal interface, allowing them to appear as creators or actors on domain objects. Also known as "service account" in some contexts.' properties: __typename: type: string id: type: string modifiedAt: format: datetime type: - 'null' - string name: type: - 'null' - string type: object ProteinDomainInput: additionalProperties: false properties: aaSequenceId: description: The ID of the AA sequence to use for the domain. type: string label: description: The label of the domain, uniquely identifying the domain within the format. type: string required: - label - aaSequenceId type: object UpdateProteinInputWithPathParams: additionalProperties: false properties: aliases: items: type: string type: array archiveReason: type: string archived: type: boolean authorIds: items: type: string type: array chains: description: A chain input for each chain on the relevant format. Must be all provided if domains are provided. items: $ref: '#/components/schemas/ProteinChainInput' type: array customFields: additionalProperties: $ref: '#/components/schemas/FieldValueInput' type: object domains: description: A domain input for each domain on the relevant format. If any are provided, all must be provided. items: $ref: '#/components/schemas/ProteinDomainInput' type: array entityRegistryId: type: string folderId: type: string id: type: string name: type: string namingStrategy: 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 registryId: type: - 'null' - string schemaFields: additionalProperties: $ref: '#/components/schemas/FieldValueInput' type: object schemaId: type: string studyIds: description: Study IDs to add the protein to. items: type: string type: array required: - id type: object FieldValueInput: additionalProperties: false properties: value: $ref: '#/components/schemas/AnyType' required: - value type: object Protein: allOf: - $ref: '#/components/schemas/IProtein' - 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.' properties: __typename: type: string authors: oneOf: - format: uri type: string - type: 'null' creator: $ref: '#/components/schemas/PrincipalRef' schemaFields: oneOf: - items: $ref: '#/components/schemas/SchemaFieldValue' type: array - type: 'null' type: object ProteinChainInput: additionalProperties: false properties: aaSequenceId: description: The ID of the AA sequence to use for the chain. type: string label: description: The label of the chain, uniquely identifying the chain within the format. type: string required: - label - aaSequenceId type: object IProtein: properties: __typename: type: string aliases: oneOf: - items: type: string type: array - type: 'null' archiveReason: type: - 'null' - string archived: type: boolean chains: description: The chains and associated amino acid sequences on the protein. items: $ref: '#/components/schemas/ProteinChain' type: array createdAt: format: datetime type: string customFields: oneOf: - items: $ref: '#/components/schemas/CustomField' type: array - type: 'null' domains: description: The domains and associated amino acid sequences on the protein. items: $ref: '#/components/schemas/ProteinDomain' type: array entityRegistryId: type: - 'null' - string folder: oneOf: - $ref: '#/components/schemas/FolderRef' - type: 'null' format: $ref: '#/components/schemas/ProteinFormatRef' description: The protein format that defines the structure (domains, chains, interactions) for the protein. fullHistory: description: '`fullHistory` is a superset of `history` that also returns inactive versions that are not part of the current version history. Versions are returned in chronological order (oldest first).' format: uri type: string history: description: 'Only the currently active version lineage, in chronological order (oldest first). If a change was made and then undone by resetting to an earlier version, the version recording that change is not relevant to the current state of the entity, so it is not included in this listing.' format: uri type: string id: type: string modifiedAt: format: datetime type: string name: type: string outOfSync: description: Indicates if constituent domain or chain entities have changed since the protein was last updated. type: boolean outOfSyncReason: description: Any additional information about why the protein is out of sync. type: - 'null' - string project: oneOf: - $ref: '#/components/schemas/ProjectRef' - type: 'null' registrationOrigin: oneOf: - $ref: '#/components/schemas/RegistrationOrigin' - type: 'null' registry: oneOf: - $ref: '#/components/schemas/RegistryRef' - type: 'null' schema: $ref: '#/components/schemas/EntitySchemaRef' type: object AsyncTaskLink: properties: pollingUri: format: uri type: string taskId: type: string type: object ArrayValue: description: A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns). properties: __typename: type: string value: items: anyOf: - $ref: '#/components/schemas/BooleanValue' - $ref: '#/components/schemas/DateTimeValue' - $ref: '#/components/schemas/DateValue' - $ref: '#/components/schemas/DecimalValue' - $ref: '#/components/schemas/IntegerValue' - $ref: '#/components/schemas/JsonValue' - $ref: '#/components/schemas/ObjectLinkValue' - $ref: '#/components/schemas/ObjectLinkListValue' - $ref: '#/components/schemas/TextAndUrlValue' - $ref: '#/components/schemas/TextValue' description: Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue discriminator: propertyName: __typename type: array type: object IntegerAppConfigSpec: description: Specifies that an app configuration field should accept an integer value. properties: __typename: type: string enum: description: Optional enum constraint — if present, the value must be one of these integers. oneOf: - items: type: integer type: array - type: 'null' requiredConfig: type: - 'null' - boolean type: object AppConfigOption: description: 'Defines a configuration option in an app''s configuration schema. Each option has a name, optional description, and a configSpec defining the expected value type and validation.' properties: __typename: type: string configSpec: anyOf: - $ref: '#/components/schemas/BooleanAppConfigSpec' - $ref: '#/components/schemas/IntegerAppConfigSpec' - $ref: '#/components/schemas/FloatAppConfigSpec' - $ref: '#/components/schemas/TextAppConfigSpec' - $ref: '#/components/schemas/SecureTextAppConfigSpec' - $ref: '#/components/schemas/DateAppConfigSpec' - $ref: '#/components/schemas/DateTimeAppConfigSpec' - $ref: '#/components/schemas/JsonAppConfigSpec' - $ref: '#/components/schemas/ArrayAppConfigSpec' - $ref: '#/components/schemas/DropdownAppConfigSpec' - $ref: '#/components/schemas/EntitySchemaAppConfigSpec' - $ref: '#/components/schemas/WorkflowTaskSchemaAppConfigSpec' - $ref: '#/components/schemas/SchemaAppConfigSpec' - $ref: '#/components/schemas/ResourceAppConfigSpec' description: Union of BooleanAppConfigSpec, IntegerAppConfigSpec, FloatAppConfigSpec, TextAppConfigSpec, SecureTextAppConfigSpec, DateAppConfigSpec, DateTimeAppConfigSpec, JsonAppConfigSpec, ArrayAppConfigSpec, DropdownAppConfigSpec, EntitySchemaAppConfigSpec, WorkflowTaskSchemaAppConfigSpec, SchemaAppConfigSpec, ResourceAppConfigSpec discriminator: propertyName: __typename description: type: - 'null' - string name: type: string type: object AppConfigDropdownOption: description: Defines an option within a dropdown-type app configuration field. properties: __typename: type: string description: type: - 'null' - string name: type: string requiredConfig: type: - 'null' - boolean type: object ObjectRef: properties: __typename: type: string id: format: api_id type: string type: object TextValue: description: A type that represents text (string) values. properties: __typename: type: string value: description: The text value. It may or may not be an empty string. type: string type: object DateTimeAppConfigSpec: description: Specifies that an app configuration field should accept a datetime value. properties: __typename: type: string requiredConfig: type: - 'null' - boolean type: object SecureTextAppConfigSpec: description: 'Specifies that an app configuration field should accept secure (encrypted) text. Used for sensitive data like API keys or credentials.' properties: __typename: type: string requiredConfig: type: - 'null' - boolean type: object parameters: 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 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 fieldset.anyOf: description: Restricts results to those whose schema implements any of the specified fieldset API IDs (custom schema interfaces). Comma-separated list. explode: false in: query name: fieldset.anyOf schema: items: type: string maxItems: 100 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 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 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 mentionedIn.anyOf: description: Restricts results to items mentioned in entries matching any of the specified entry IDs. Comma-separated list. explode: false in: query name: mentionedIn.anyOf schema: items: type: string maxItems: 100 type: array 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 name.anyOf: description: Restricts results to those that match any of the specified names. Case insensitive. Warning - this filter can be non-performant due to case insensitivity. Ensure only one name filter is used at a time. Comma-separated list. explode: false in: query name: name.anyOf schema: items: type: string maxItems: 100 type: array name.anyOf.caseSensitive: description: Restricts results to those that match any of the specified names. Case sensitive. Ensure only one name filter is used at a time. Comma-separated list. explode: false in: query name: name.anyOf.caseSensitive 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.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 authors.anyOf: description: Restricts results to those whose author matches any of the specified user or author IDs. Comma-separated list. explode: false in: query name: authors.anyOf schema: items: type: string maxItems: 100 type: array project.eq: description: ID of a project. Restricts results to those in the project. in: query name: project.eq schema: type: string registry.eq: description: ID of a registry. Restricts results to those registered in this registry. Specifying "null" returns unregistered items. in: query name: registry.eq schema: type: string schema.anyOf: description: Restricts results to those that match any of the specified schema IDs. Use only one `schema` filter arg at a time. Comma-separated list. explode: false in: query name: schema.anyOf schema: items: type: string maxItems: 100 type: array nextToken: description: Token for pagination in: query name: nextToken schema: type: string systemCategory.anyOf: description: Restricts results to those whose schema implements any of the specified system category API IDs (non-exclusive static schema interfaces). Comma-separated list. explode: false in: query name: systemCategory.anyOf schema: items: type: string maxItems: 100 type: array pageSize: description: Number of results to return. Defaults to 50, maximum of 100. in: query name: pageSize schema: type: integer 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 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 creator.anyOf: description: Restricts results to those created by any of the specified user IDs. Comma-separated list. explode: false in: query name: creator.anyOf schema: items: type: string maxItems: 100 type: array 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 schema.eq: description: Single schema ID. Restricts results to those that match the specified schema exactly. Use only one `schema` filter arg at a time. in: query name: schema.eq schema: type: string responses: 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 InternalServerError: content: application/problem+json: schema: $ref: '#/components/schemas/InternalServerError' description: Internal Server Error 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 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