openapi: 3.0.1
info:
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Benchling AA Sequences Data Frames 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: Data frames in Benchling represent tabular data that is not schematized. They contain columns with defined types and rows of data. Data frames are primarily used within specific Benchling applications. For example, in Benchling Analysis, each table is represented as a dataframe that is visible only within the analysis.
  name: Data Frames
paths:
  /data-frames:
    post:
      description: "Create a data frame.\n\nData frames can be created from `.csv` files, and only 1 `.csv` file can currently be uploaded.\n\nA successful data frame upload requires 3 calls in serial:\n1. [Create a data frame](#/Data%20Frames/createDataFrame), this endpoint, specifying the files to upload. This\n   returns a `manifest` containing S3 `PUT` URLs corresponding to the files that will be uploaded for\n   the 2nd call and a data frame ID for the 3rd call.\n2. Upload the data frame `.csv` content to S3. Add `x-amz-server-side-encryption: AES256` to the request\n   headers, because we use server-side encryption. Here is a `curl` example:\n   ```bash\n   curl -H \"x-amz-server-side-encryption: AES256\" -X PUT -T <LOCAL_FILE> -L <S3_PUT_URL>\n   ```\n3. [Update the data frame](#/Data%20Frames/patchDataFrame) to mark as `IN_PROGRESS` to start a [long-running task](#/Tasks/getTask)\n  to process and validate the data frame.\n    - For more details on how we process and validate data frames, [click here](https://docs.benchling.com/docs/datasets-ingestion-reference).\n\nNote: Manifest URLs are valid for 1 hour after being returned from this endpoint. They should not be stored\npersistently for later use.\n\nCSV files up to 150MB are supported.\n"
      operationId: createDataFrame
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataFrameCreate'
      responses:
        '200':
          content:
            application/json:
              example:
                errorMessage: null
                id: dset_LlDFupKyErxx
                manifest:
                - fileName: 09-14-2022_011620_PM_well_plate-part-00000.csv
                  url: https://benchling-location.s3.amazonaws.com/deploys/location/data_frames/source_files/.../09-14-2022_011620_PM_well_plate-part-00000.csv?...
                name: 09-14-2022 01:16:20 PM well plate
                uploadStatus: NOT_UPLOADED
              schema:
                $ref: '#/components/schemas/DataFrame'
          description: OK
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
      summary: Create a data frame.
      tags:
      - Data Frames
  /data-frames/{data_frame_id}:
    get:
      description: "Get a data frame and URLs to download its data.\n\nIf the data frame has `SUCCEEDED` status, the `manifest` field in the response will contain URLs to each\npart of a data frame that can be downloaded and the names of the files.\n\nIf the data frame has `NOT_UPLOADED` status, the `manifest` field in the response will contain S3 `PUT` URLs\nto upload data frame `.csv` files. See [Create a data frame](#/Data%20Frames/createDataFrames) for documentation of\nthe full upload flow.\n\nIf the data frame has `FAILED_VALIDATION` or `IN_PROGRESS` status, the `manifest` field in the response will\nonly contain the names of the files and urls will be `null`.\n\nNotes:\n  - Using this endpoint with `rowDataFormat=csv` might be slow and timeout on large data frames.\n   We suggest using `rowDataFormat=parquet` for large data frames.\n  - Parquet files contain column system names, which are unique column identifiers within the\n    data frame and may be different from the column display names. The `columns` part of the\n    response provides the display name and corresponding system name for each column.\n  - CSV files contain column display names.\n  - Manifest URLs are valid for 1 hour after being returned from this endpoint. They should not be stored\npersistently for later use.\n"
      operationId: getDataFrame
      parameters:
      - description: The ID of the data frame
        in: path
        name: data_frame_id
        required: true
        schema:
          example: dset_LlDFupKyErxx
          type: string
      - description: Comma-separated list of fields to return. Modifies the output shape. To return all keys at a given level, enumerate them or use the wildcard, '*'. For more information, [click here](https://docs.benchling.com/docs/getting-started-1#returning-query-parameter).
        in: query
        name: returning
        schema:
          example: id,modifiedAt
          type: string
      - description: The format of the row data, either `csv` or `parquet`. Default is `csv`.
        in: query
        name: rowDataFormat
        schema:
          enum:
          - csv
          - parquet
          example: csv
          type: string
      responses:
        '200':
          content:
            application/json:
              examples:
                1 Succeeded:
                  description: A Data Frame that was created successfully. `manifest` contains URLs that can be used to download the data.
                  value:
                    columns:
                    - displayName: Name
                      systemName: name
                      type:
                        isList: false
                        isNullable: false
                        name: String
                    errorMessage: null
                    id: dset_LlDFupKyErxx
                    manifest:
                    - fileName: 09-14-2022_011620_PM_well_plate-part-00000.csv
                      url: https://benchling-location.s3.amazonaws.com/deploys/location/data_frames/.../09-14-2022_011620_PM_well_plate-part-00000.csv?...
                    name: 09-14-2022 01:16:20 PM well plate
                    uploadStatus: SUCCEEDED
                2 Failed Validation:
                  description: A Data Frame that failed validation.
                  value:
                    errorMessage: Invalid CSV File.
                    id: dset_LlDFupKyErxx
                    manifest:
                    - fileName: 09-14-2022_011620_PM_well_plate-part-00000.csv
                      url: null
                    name: 09-14-2022 01:16:20 PM well plate
                    uploadStatus: FAILED_VALIDATION
                3 In Progress:
                  description: A Data Frame still being processed.
                  value:
                    errorMessage: null
                    id: dset_LlDFupKyErxx
                    manifest:
                    - fileName: 09-14-2022_011620_PM_well_plate-part-00000.csv
                      url: null
                    name: 09-14-2022 01:16:20 PM well plate
                    uploadStatus: IN_PROGRESS
                4 Not Uploaded:
                  description: An empty Data Frame. Files can be uploaded by using the provided manifest URLs.
                  value:
                    errorMessage: null
                    id: dset_LlDFupKyErxx
                    manifest:
                    - fileName: 09-14-2022_011620_PM_well_plate-part-00000.csv
                      url: https://benchling-location.s3.amazonaws.com/deploys/location/data_frames/source_files/.../09-14-2022_011620_PM_well_plate-part-00000.csv?...
                    name: 09-14-2022 01:16:20 PM well plate
                    uploadStatus: NOT_UPLOADED
              schema:
                $ref: '#/components/schemas/DataFrame'
          description: OK
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
      summary: Get a data frame
      tags:
      - Data Frames
    patch:
      description: 'Update a data frame.


        After uploading a `.csv` data drame file to S3, call this endpoint to mark the upload status as `IN_PROGRESS`

        to launch a [long-running task](#/Tasks/getTask) to validate and transform the raw `.csv` file into a

        data frame. Once complete, the data frame''s status will either be updated to `SUCCEEDED` or `FAILED_VALIDATION`.


        For more details on how we process and validate data frames, [click here](https://docs.benchling.com/docs/datasets-ingestion-reference).


        See [Create a data frame](#/Data%20Frames/createDataFrame) for documentation of the full upload flow.

        '
      operationId: patchDataFrame
      parameters:
      - description: The ID of the data frame
        in: path
        name: data_frame_id
        required: true
        schema:
          example: dset_LlDFupKyErxx
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataFrameUpdate'
      responses:
        '202':
          content:
            application/json:
              example:
                taskId: task_b2ZtLWZha2UtZGVwbG95LWhlbGxvX3dvcmxkOm9mbS1mYWtlLWRlcGxveS1oZWxsb193b3JsZC1zZXEtMTIzNDU2Nzg=
              schema:
                $ref: '#/components/schemas/AsyncTaskLink'
          description: 'This endpoint launches a [long-running task](#/Tasks/getTask) and returns the Task ID of the launched task.

            When successful, the task returns the [DataFrame](#/components/schemas/DataFrame) resource for the related data frame.

            '
        '400':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/BadRequestError'
          description: Bad Request
        '403':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ForbiddenError'
          description: Forbidden
        '404':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/NotFoundError'
          description: Not Found
      summary: Update a data frame
      tags:
      - Data Frames
components:
  schemas:
    BadRequestError:
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/BaseError'
          - properties:
              type:
                enum:
                - invalid_request_error
                type: string
      type: object
    ForbiddenError:
      properties:
        error:
          properties:
            invalidId:
              type: string
            message:
              type: string
            type:
              type: string
            userMessage:
              type: string
          type: object
      type: object
    DataFrameManifest:
      properties:
        manifest:
          example:
          - fileName: 09-14-2022_011620_PM_well_plate-part-00000.csv
            url: https://benchling-location.s3.amazonaws.com/deploys/location/data_frames/.../09-14-2022_011620_PM_well_plate-part-00000.csv?...
          items:
            description: List of files composing a data frane, their names, and their corresponding URLs.
            properties:
              fileName:
                type: string
              url:
                nullable: true
                type: string
            type: object
          type: array
      type: object
    NotFoundError:
      properties:
        error:
          allOf:
          - $ref: '#/components/schemas/BaseError'
          - properties:
              invalidId:
                type: string
              type:
                enum:
                - invalid_request_error
                type: string
      type: object
    DataFrameColumnTypeMetadata:
      allOf:
      - $ref: '#/components/schemas/DataFrameColumnTypeNameEnum'
      - properties:
          isList:
            type: boolean
          isNullable:
            type: boolean
          target:
            description: Only present if the column type is ObjectLink
            properties:
              baseTypeName:
                example: DNASequence
                type: string
              schemaId:
                example: ts_n4l12nf0
                nullable: true
                type: string
            type: object
        required:
        - isNullable
        - isList
        type: object
    BaseError:
      properties:
        message:
          type: string
        type:
          type: string
        userMessage:
          type: string
      type: object
    DataFrameCreate:
      allOf:
      - $ref: '#/components/schemas/DataFrameCreateManifest'
      - properties:
          name:
            example: 09-14-2022 01:16:20 PM well plate
            type: string
        required:
        - manifest
        - name
        type: object
    DataFrameCreateManifest:
      properties:
        manifest:
          example:
          - fileName: 09-14-2022_011620_PM_well_plate-part-00000.csv
          items:
            description: List of files that will be uploaded to a data frame and their names.
            properties:
              fileName:
                type: string
            type: object
          type: array
      type: object
    DataFrameUpdate:
      properties:
        uploadStatus:
          enum:
          - IN_PROGRESS
          type: string
      type: object
    DataFrameColumnMetadata:
      properties:
        displayName:
          type: string
        type:
          allOf:
          - $ref: '#/components/schemas/DataFrameColumnTypeMetadata'
      type: object
    DataFrame:
      allOf:
      - $ref: '#/components/schemas/FileStatus'
      - $ref: '#/components/schemas/DataFrameManifest'
      - properties:
          columns:
            example:
            - displayName: Well
              type:
                isList: false
                isNullable: false
                name: ObjectLink
                target:
                  baseTypeName: DNASequence
                  schemaId: ts_n4l12nf0
            items:
              $ref: '#/components/schemas/DataFrameColumnMetadata'
            type: array
          id:
            example: dset_LlDFupKyErxx
            type: string
          name:
            description: The user-facing name for this DataFrame.
            example: 09-14-2022 01:16:20 PM well plate
            type: string
        type: object
    AsyncTaskLink:
      properties:
        taskId:
          type: string
      type: object
    FileStatus:
      properties:
        errorMessage:
          example: null
          nullable: true
          type: string
        uploadStatus:
          enum:
          - IN_PROGRESS
          - SUCCEEDED
          - FAILED_VALIDATION
          - NOT_UPLOADED
          example: SUCCEEDED
          type: string
      type: object
    DataFrameColumnTypeNameEnum:
      properties:
        name:
          enum:
          - String
          - Int
          - Float
          - JSON
          - DateTime
          - Date
          - Boolean
          - ObjectLink
          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