Benchling Lab Automation API

openapi: 3.0.1
info:
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Benchling AA Sequences Lab Automation API
  version: 2.0.0
  description: 'AA Sequences are the working units of cells that make everything run (they help make structures, catalyze reactions and allow for signaling - a kind of internal cell communication). On Benchling, these are comprised of a string of amino acids and collections of other attributes, such as annotations.

    '
servers:
- url: /api/v2
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: Lab Automation endpoints support integration with lab instruments, and liquid handlers to create samples or results, and capture transfers between containers at scale.
  name: Lab Automation
paths:
  /automation-file-transforms/{transform_id}:
    get:
      description: Get a Lab Automation Transform step
      operationId: getLabAutomationTransform
      parameters:
      - in: path
        name: transform_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabAutomationTransform'
          description: OK
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
      summary: Get a Lab Automation Transform step
      tags:
      - Lab Automation
    patch:
      description: Update a Lab Automation Transform step
      operationId: updateLabAutomationTransform
      parameters:
      - in: path
        name: transform_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/LabAutomationTransformUpdate'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/LabAutomationTransform'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: Update a Lab Automation Transform step
      tags:
      - Lab Automation
  /automation-input-generators/{input_generator_id}:
    get:
      description: Get an Automation Input Generator
      operationId: getAutomationInputGenerator
      parameters:
      - in: path
        name: input_generator_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationInputGenerator'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: Get an Automation Input Generator
      tags:
      - Lab Automation
    patch:
      description: Update an Automation Input Generator
      operationId: updateAutomationInputGenerator
      parameters:
      - in: path
        name: input_generator_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationInputGeneratorUpdate'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationInputGenerator'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: Update an Automation Input Generator
      tags:
      - Lab Automation
  /automation-input-generators/{input_generator_id}:generate-input:
    post:
      description: Generate Input with an Automation Input Generator
      operationId: generateInputWithAutomationInputGenerator
      parameters:
      - in: path
        name: input_generator_id
        required: true
        schema:
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncTaskLink'
          description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.

            The task response contains the Automation Input Generator with the generated file.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: Generate Input with an Automation Input Generator
      tags:
      - Lab Automation
  /automation-output-processors:
    get:
      description: List Automation Output Processors which have an attached file
      operationId: listAutomationOutputProcessors
      parameters:
      - description: Id of the Run
        in: query
        name: assayRunId
        schema:
          type: string
      - description: Name of the Automation File Config
        in: query
        name: automationFileConfigName
        schema:
          type: string
      - description: 'Archive reason. Restricts items to those with the specified archive reason. Use "NOT_ARCHIVED" to filter for unarchived processors. Use "ANY_ARCHIVED" to filter for archived processors regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived.

          '
        examples:
          1_not_archived:
            summary: Only include unarchived items (default).
            value: NOT_ARCHIVED
          2_archived_reason:
            summary: Includes items archived for a specific reason.
            value: Retired
          3_any_archived:
            summary: Includes items archived for any reason.
            value: ANY_ARCHIVED
          4_any_archived_or_not_archived:
            summary: Includes both archived and unarchived items.
            value: ANY_ARCHIVED_OR_NOT_ARCHIVED
        in: query
        name: archiveReason
        schema:
          type: string
      - description: 'Datetime, in RFC 3339 format. Supports the > and < operators. Time zone defaults to UTC. Restricts results to those modified in the specified range. e.g. > 2017-04-30. Date ranges can be specified with the following nomenclature > YYYY-MM-DD AND <YYYY-MM-DD.

          '
        examples:
          and-range:
            summary: Filter for all models modified within a certain range using the AND operator.
            value: '> 2022-03-01 AND < 2022-04-01'
          full-rfc-3339-format:
            summary: Filter for modified models using the full RFC 3339 format
            value: '> 2020-12-31T21:07:14-05:00'
          greater-than-example:
            summary: Filter for all models modified after a certain date
            value: '> 2022-03-01'
        in: query
        name: modifiedAt
        schema:
          type: string
      - description: Token for pagination
        in: query
        name: nextToken
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationOutputProcessorsPaginatedList'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: List non-empty Automation Output Processors
      tags:
      - Lab Automation
    post:
      description: Create Automation Output Processor
      operationId: createAutomationOutputProcessor
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationOutputProcessorCreate'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationOutputProcessor'
          description: Created
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: Create Automation Output Processor
      tags:
      - Lab Automation
  /automation-output-processors/{output_processor_id}:
    get:
      description: Get an Automation Output Processor
      operationId: getAutomationOutputProcessor
      parameters:
      - in: path
        name: output_processor_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationOutputProcessor'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: Get an Automation Output Processor
      tags:
      - Lab Automation
    patch:
      description: Update an Automation Output Processor
      operationId: updateAutomationOutputProcessor
      parameters:
      - in: path
        name: output_processor_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationOutputProcessorUpdate'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationOutputProcessor'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: Update an Automation Output Processor
      tags:
      - Lab Automation
  /automation-output-processors/{output_processor_id}:process-output:
    post:
      description: Process Output with an Automation Output Processor
      operationId: processOutputWithAutomationOutputProcessor
      parameters:
      - in: path
        name: output_processor_id
        required: true
        schema:
          type: string
      responses:
        '202':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AsyncTaskLink'
          description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.

            The task response contains the Automation Output Processor that was processed.


            Any created Benchling objects may take a few seconds to appear in search.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: Process Output with an Automation Output Processor
      tags:
      - Lab Automation
  /automation-output-processors:archive:
    post:
      description: Archive Automation Output Processors and linked Results
      operationId: archiveAutomationOutputProcessors
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationOutputProcessorsArchive'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationOutputProcessorArchivalChange'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: Archive Automation Output Processors and linked Results
      tags:
      - Lab Automation
  /automation-output-processors:unarchive:
    post:
      description: Unarchive Automation Output Processors and linked Results
      operationId: unarchiveAutomationOutputProcessors
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AutomationOutputProcessorsUnarchive'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AutomationOutputProcessorArchivalChange'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
      summary: Unarchive Automation Output Processors and linked Results
      tags:
      - Lab Automation
components:
  schemas:
    LabAutomationTransformUpdate:
      additionalProperties: false
      properties:
        blobId:
          description: The ID of a blob link or the API ID of a file to process.
          example: cd624536-c6ba-41b9-b802-9461689e2ea3 or file_65Cevxgm
          type: string
        errors:
          items:
            $ref: '#/components/schemas/LabAutomationBenchlingAppError'
          type: array
      type: object
    LabAutomationTransform:
      properties:
        apiURL:
          description: The canonical url of the transform in the API.
          format: uri
          readOnly: true
          type: string
        blobId:
          format: uuid
          nullable: true
          type: string
        customTransformId:
          format: uuid
          nullable: true
          type: string
        errors:
          $ref: '#/components/schemas/LabAutomationBenchlingAppErrors'
        id:
          type: string
        inputGeneratorId:
          nullable: true
          type: string
        modifiedAt:
          description: DateTime the transform was last modified.
          format: date-time
          readOnly: true
          type: string
        outputProcessorId:
          nullable: true
          type: string
        status:
          enum:
          - NOT_STARTED
          - RUNNING
          - FAILED
          - SUCCEEDED
          type: string
      type: object
    Blob:
      properties:
        id:
          description: The universally unique identifier (UUID) for the blob.
          example: c33fe52d-fe6a-4c98-adcd-211bdf6778f7
          format: uuid
          type: string
        mimeType:
          description: eg. application/jpeg
          example: text/csv
          maxLength: 100
          type: string
        name:
          description: Name of the blob
          example: MyInstrumentInputFile.csv
          maxLength: 1000
          type: string
        type:
          description: 'One of RAW_FILE or VISUALIZATION. If VISUALIZATION, the blob may be displayed as an image preview.

            '
          enum:
          - RAW_FILE
          - VISUALIZATION
          type: string
        uploadStatus:
          enum:
          - IN_PROGRESS
          - COMPLETE
          - ABORTED
          type: string
      type: object
    AutomationOutputProcessorsPaginatedList:
      description: A paginated list of automation output processors which have an attached file.
      properties:
        automationOutputProcessors:
          items:
            $ref: '#/components/schemas/AutomationOutputProcessor'
          type: array
        nextToken:
          example: Im5ldyB0ZXN0Ig==
          type: string
      type: object
    AutomationOutputProcessor:
      allOf:
      - $ref: '#/components/schemas/AutomationFile'
      - properties:
          apiURL:
            description: The canonical url of the Automation Output Processor in the API.
            example: https://benchling.com/api/v2/automation-output-processors/aop_C3wGA9HF
            format: uri
            readOnly: true
            type: string
          archiveRecord:
            allOf:
            - $ref: '#/components/schemas/ArchiveRecord'
            nullable: true
          completeWithErrors:
            description: Specifies whether file processing should complete with errors. False means any error in output file processing will result in no actions being committed. True means that if row-level errors occur, then failing rows and their errors will be saved to errorFile, and actions from successful rows will be committed.
            type: boolean
          createdAt:
            description: DateTime the Automation Output Processor was created
            format: date-time
            type: string
          errorFile:
            allOf:
            - $ref: '#/components/schemas/Blob'
            nullable: true
          id:
            example: aop_C3wGA9HF
            type: string
          modifiedAt:
            description: DateTime the Automation Output Processor was last modified
            format: date-time
            type: string
          progressStats:
            $ref: '#/components/schemas/AutomationProgressStats'
          transforms:
            items:
              allOf:
              - $ref: '#/components/schemas/LabAutomationTransform'
              nullable: true
            type: array
        type: object
    BadRequestError:
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/BaseError'
          - properties:
              type:
                enum:
                - invalid_request_error
                type: string
      type: object
    AutomationOutputProcessorArchivalChange:
      description: IDs of all items that were archived or unarchived, grouped by resource type. This includes the IDs of any linked Results that were archived / unarchived.
      properties:
        automationOutputProcessorIds:
          items:
            type: string
          type: array
        resultIds:
          items:
            type: string
          type: array
      type: object
    BaseError:
      properties:
        message:
          type: string
        type:
          type: string
        userMessage:
          type: string
      type: object
    ArchiveRecord:
      properties:
        reason:
          example: Made in error
          type: string
      type: object
    AutomationOutputProcessorCreate:
      additionalProperties: false
      properties:
        assayRunId:
          type: string
        automationFileConfigName:
          type: string
        completeWithErrors:
          description: Specifies whether file processing should complete with errors. False means any error in output file processing will result in no actions being committed. True means that if row-level errors occur, then failing rows and their errors will be saved to errorFile, and actions from successful rows will be committed.
          type: boolean
        fileId:
          description: The ID of a blob link or the API ID of a file to process.
          example: cd624536-c6ba-41b9-b802-9461689e2ea3 or file_65Cevxgm
          type: string
        folderId:
          description: The API ID of the folder to set for the automation output file. Folder items created by the correpsonding output processor will be created in this folder.
          type: string
        locationId:
          description: The API ID of the location to set for the automation output file. Storable items created by the correpsonding output processor will be created at this location.
          type: string
        timezone:
          description: The timezone to set for the automation output file. Used as the timezone for the timestamp fields if not set in the timestamp.
          type: string
      required:
      - fileId
      - automationFileConfigName
      - assayRunId
      type: object
    AutomationProgressStats:
      description: Processing progress information.
      properties:
        rowsFailed:
          type: integer
        rowsSucceeded:
          type: integer
        rowsUnprocessed:
          type: integer
      type: object
    AsyncTaskLink:
      properties:
        taskId:
          type: string
      type: object
    LabAutomationBenchlingAppErrors:
      properties:
        topLevelErrors:
          items:
            properties:
              errorMessage:
                type: string
            type: object
          type: array
      type: object
    AutomationOutputProcessorsUnarchive:
      additionalProperties: false
      properties:
        automationOutputProcessorIds:
          description: Array of automation output processor IDs
          items:
            type: string
          type: array
      required:
      - automationOutputProcessorIds
      type: object
    AutomationOutputProcessorUpdate:
      additionalProperties: false
      properties:
        fileId:
          description: The ID of a blob link or the API ID of a file to process.
          example: cd624536-c6ba-41b9-b802-9461689e2ea3 or file_65Cevxgm
          type: string
      required:
      - fileId
      type: object
    LabAutomationBenchlingAppError:
      properties:
        message:
          type: string
      type: object
    NotFoundError:
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/BaseError'
          - properties:
              invalidId:
                type: string
              type:
                enum:
                - invalid_request_error
                type: string
      type: object
    AutomationFile:
      properties:
        assayRunId:
          example: 588aca02-1a20-4b94-a40f-b3f3a0081749
          type: string
        automationFileConfig:
          properties:
            name:
              example: MyInstrumentName
              type: string
          type: object
        file:
          allOf:
          - $ref: '#/components/schemas/Blob'
          nullable: true
        id:
          type: string
        status:
          enum:
          - SUCCEEDED
          - FAILED
          - NOT_STARTED
          - RUNNING
          type: string
      type: object
    AutomationOutputProcessorsArchive:
      additionalProperties: false
      properties:
        automationOutputProcessorIds:
          description: Array of automation output processor IDs
          items:
            type: string
          type: array
        reason:
          description: 'The reason that the output processors are being archived. Accepted reasons may differ based on tenant configuration.

            '
          enum:
          - Made in error
          - Retired
          - Expended
          - Shipped
          - Contaminated
          - Expired
          - Missing
          - Other
          type: string
      required:
      - automationOutputProcessorIds
      type: object
    AutomationInputGenerator:
      allOf:
      - $ref: '#/components/schemas/AutomationFile'
      - properties:
          apiURL:
            description: The canonical url of the Automation Input Generator in the API.
            example: https://benchling.com/api/v2/automation-input-generators/aif_C3wGA9HF
            format: uri
            readOnly: true
            type: string
          createdAt:
            description: DateTime the Automation Input Generator was last modified
            format: date-time
            readOnly: true
            type: string
          id:
            example: aif_C3wGA9HF
            type: string
          modifiedAt:
            description: DateTime the Automation Input Generator was last modified
            format: date-time
            readOnly: true
            type: string
          transforms:
            items:
              allOf:
              - $ref: '#/components/schemas/LabAutomationTransform'
              nullable: true
            type: array
        type: object
    AutomationInputGeneratorUpdate:
      additionalProperties: false
      properties:
        fileId:
          description: The ID of the file (blob) associated with the input generator. Set to `null` to remove an existing file from the generator.
          example: null
          nullable: true
          type: string
      type: object
  securitySchemes:
    basicApiKeyAuth:
      description: Use issued API key for standard access to the API
      scheme: basic
      type: http
    basicClientIdSecretAuth:
      description: Auth used as part of client credentials OAuth flow prior to receiving a bearer token.
      scheme: basic
      type: http
    oAuth:
      description: OAuth2 Client Credentials flow intended for service access
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /api/v2/token
      type: oauth2
externalDocs:
  description: Additional API Documentation
  url: https://docs.benchling.com