openapi: 3.2.0
info:
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Benchling App Installation API
  version: 2.0.0
  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.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- 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.'
  name: AppInstallation
  x-bnch-organization: Benchling
paths:
  /app-installation/items:
    get:
      description: List AppInstallation items.
      operationId: AppInstallation.List
      parameters:
      - $ref: '#/components/parameters/archiveReason.anyOf'
      - $ref: '#/components/parameters/archived.anyOf'
      - $ref: '#/components/parameters/createdAt.gt'
      - $ref: '#/components/parameters/createdAt.gte'
      - $ref: '#/components/parameters/createdAt.lt'
      - $ref: '#/components/parameters/createdAt.lte'
      - $ref: '#/components/parameters/creator.anyOf'
      - $ref: '#/components/parameters/id.anyOf'
      - $ref: '#/components/parameters/modifiedAt.gt'
      - $ref: '#/components/parameters/modifiedAt.gte'
      - $ref: '#/components/parameters/modifiedAt.lt'
      - $ref: '#/components/parameters/modifiedAt.lte'
      - $ref: '#/components/parameters/name.anyOf'
      - $ref: '#/components/parameters/name.anyOf.caseSensitive'
      - $ref: '#/components/parameters/nextToken'
      - $ref: '#/components/parameters/omit'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/returning'
      - description: 'Method by which to order results. Valid sorts are: createdAt (created time, oldest first) and modifiedAt (modified time, oldest first). Use :asc or :desc to specify ascending or descending order. Default is modifiedAt:desc.'
        in: query
        name: sort
        schema:
          default: modifiedAt:desc
          enum:
          - createdAt:asc
          - createdAt:desc
          - modifiedAt:asc
          - modifiedAt:desc
          type: string
      - description: Set to true to access beta operations via /api/v3.
        in: header
        name: EARLY-ACCESS
        required: false
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AppInstallationPaginatedList'
          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 AppInstallation items
      tags:
      - AppInstallation
      x-bnch-rate-limit-tier: 4
  /app-installation/{app_installation_id}:
    get:
      description: Get a single AppInstallation by ID.
      operationId: AppInstallation.Get
      parameters:
      - description: ID of the AppInstallation.
        in: path
        name: app_installation_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/AppInstallation'
          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 AppInstallation by ID
      tags:
      - AppInstallation
      x-bnch-rate-limit-tier: 5
  /app-installation/{app_installation_id}/configuration-values/items:
    get:
      description: List AppConfigValue items.
      operationId: AppInstallation.configurationValues.List
      parameters:
      - description: ID of the AppInstallation.
        in: path
        name: app_installation_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/AppConfigValueUnpaginatedList'
          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 AppConfigValue items
      tags:
      - AppInstallation
      x-bnch-rate-limit-tier: 4
components:
  parameters:
    pageSize:
      description: Number of results to return. Defaults to 50, maximum of 100.
      in: query
      name: pageSize
      schema:
        type: integer
    createdAt.gte:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or after the specified time. e.g. >= 2017-04-30.
      in: query
      name: createdAt.gte
      schema:
        format: datetime
        type: string
    modifiedAt.gt:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified after the specified time. e.g. > 2017-04-30.
      in: query
      name: modifiedAt.gt
      schema:
        format: datetime
        type: string
    modifiedAt.lte:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or before the specified time. e.g. <= 2017-04-30.
      in: query
      name: modifiedAt.lte
      schema:
        format: datetime
        type: string
    id.anyOf:
      description: Restricts results to those matching any of the specified IDs. Comma-separated list.
      explode: false
      in: query
      name: id.anyOf
      schema:
        items:
          type: string
        maxItems: 100
        type: array
    omit:
      description: Comma-separated list of top-level fields to omit from each returned item. Cannot overlap with returning.
      explode: false
      in: query
      name: omit
      schema:
        items:
          type: string
        type: array
    modifiedAt.lt:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified before the specified time. e.g. < 2017-04-30.
      in: query
      name: modifiedAt.lt
      schema:
        format: datetime
        type: string
    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
    createdAt.gt:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created after the specified time. e.g. > 2017-04-30.
      in: query
      name: createdAt.gt
      schema:
        format: datetime
        type: string
    createdAt.lt:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created before the specified time. e.g. < 2017-04-30.
      in: query
      name: createdAt.lt
      schema:
        format: datetime
        type: string
    archiveReason.anyOf:
      description: Restricts items to those with any of the specified archive reasons. Use "NOT_ARCHIVED" to filter for unarchived items. Use "ANY_ARCHIVED" to filter for archived items regardless of reason. Use "ANY_ARCHIVED_OR_NOT_ARCHIVED" to return items for both archived and unarchived. Comma-separated list.
      explode: false
      in: query
      name: archiveReason.anyOf
      schema:
        items:
          type: string
        maxItems: 10
        type: array
    returning:
      description: Comma-separated list of top-level fields to include in each returned item. Cannot overlap with omit.
      explode: false
      in: query
      name: returning
      schema:
        items:
          type: string
        type: array
    archived.anyOf:
      description: If true, returns archived items. If false, returns unarchived items. If both true and false, returns archived and unarchived items. Comma-separated list.
      explode: false
      in: query
      name: archived.anyOf
      schema:
        items:
          type: boolean
        maxItems: 2
        type: array
    nextToken:
      description: Token for pagination
      in: query
      name: nextToken
      schema:
        type: string
    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
    modifiedAt.gte:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those modified at or after the specified time. e.g. >= 2017-04-30.
      in: query
      name: modifiedAt.gte
      schema:
        format: datetime
        type: string
    createdAt.lte:
      description: Datetime, in RFC 3339 format. Time zone defaults to UTC. Restricts results to those created at or before the specified time. e.g. <= 2017-04-30.
      in: query
      name: createdAt.lte
      schema:
        format: datetime
        type: string
  responses:
    NotFound:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Not Found
    TooManyRequests:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Too Many Requests
    BadRequest:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Bad Request
    Forbidden:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/GeneralError'
      description: Forbidden
    InternalServerError:
      content:
        application/problem+json:
          schema:
            $ref: '#/components/schemas/InternalServerError'
      description: Internal Server Error
  schemas:
    AppConfigValueUnpaginatedList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/AppConfigValue'
          type: array
      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
    TextAppConfigValue:
      description: Stores a text string value in an app configuration field.
      properties:
        __typename:
          type: string
        value:
          type:
          - 'null'
          - string
      type: object
    ArrayElementAppConfigValue:
      description: Stores an element value within an array-type app configuration.
      properties:
        __typename:
          type: string
        value:
          type:
          - 'null'
          - string
      type: object
    DateAppConfigValue:
      description: Stores a date value in an app configuration field.
      properties:
        __typename:
          type: string
        value:
          format: date
          type:
          - 'null'
          - string
      type: object
    IntegerAppConfigValue:
      description: Stores an integer value in an app configuration field.
      properties:
        __typename:
          type: string
        value:
          type:
          - 'null'
          - integer
      type: object
    EntitySchemaAppConfigValue:
      description: 'Stores a reference to an entity schema in an app configuration field.

        Kept separate from ResourceAppConfigValue because it carries a subtype

        identifying the kind of entity (DNA sequence, AA sequence, etc.).'
      properties:
        __typename:
          type: string
        subtype:
          description: Identifies the entity subtype of the configured schema (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
        value:
          type:
          - 'null'
          - string
      type: object
    InternalServerError:
      properties:
        detail:
          type:
          - 'null'
          - string
          - object
        errorId:
          type: string
        instance:
          type: string
        status:
          type: integer
        title:
          type:
          - 'null'
          - string
        type:
          type: string
      required:
      - type
      - title
      - detail
      - status
      - instance
      type: object
    SecureTextAppConfigValue:
      description: 'Stores a secure (encrypted) text value in an app configuration field.

        Used for sensitive data like API keys or credentials.'
      properties:
        __typename:
          type: string
        value:
          type:
          - 'null'
          - string
      type: object
    AppInstallationPaginatedList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/AppInstallation'
          type: array
        nextToken:
          type: string
      type: object
    PrincipalRef:
      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
    JsonAppConfigValue:
      description: Stores a JSON value (as a string) in an app configuration field.
      properties:
        __typename:
          type: string
        value:
          type:
          - 'null'
          - string
      type: object
    AppConfigValue:
      description: 'Represents a configured value for a Benchling App on a specific tenant. Each config

        value has a path identifying its location in the configuration hierarchy and valueData

        containing the actual value. Config values are defined by the app''s configuration spec

        and set during installation or later configuration.'
      properties:
        __typename:
          type: string
        createdAt:
          description: DateTime at which the config value was created.
          format: datetime
          type:
          - 'null'
          - string
        description:
          type:
          - 'null'
          - string
        id:
          type: string
        modifiedAt:
          description: DateTime at which the config value was last modified.
          format: datetime
          type:
          - 'null'
          - string
        path:
          items:
            type: string
          type: array
        valueData:
          description: Union of BooleanAppConfigValue, IntegerAppConfigValue, FloatAppConfigValue, TextAppConfigValue, SecureTextAppConfigValue, DateAppConfigValue, DateTimeAppConfigValue, JsonAppConfigValue, ArrayElementAppConfigValue, EntitySchemaAppConfigValue, ResourceAppConfigValue
          oneOf:
          - anyOf:
            - $ref: '#/components/schemas/BooleanAppConfigValue'
            - $ref: '#/components/schemas/IntegerAppConfigValue'
            - $ref: '#/components/schemas/FloatAppConfigValue'
            - $ref: '#/components/schemas/TextAppConfigValue'
            - $ref: '#/components/schemas/SecureTextAppConfigValue'
            - $ref: '#/components/schemas/DateAppConfigValue'
            - $ref: '#/components/schemas/DateTimeAppConfigValue'
            - $ref: '#/components/schemas/JsonAppConfigValue'
            - $ref: '#/components/schemas/ArrayElementAppConfigValue'
            - $ref: '#/components/schemas/EntitySchemaAppConfigValue'
            - $ref: '#/components/schemas/ResourceAppConfigValue'
            discriminator:
              propertyName: __typename
          - type: 'null'
      type: object
    DateTimeAppConfigValue:
      description: Stores a datetime value in an app configuration field.
      properties:
        __typename:
          type: string
        value:
          type:
          - 'null'
          - string
      type: object
    ResourceAppConfigValue:
      description: 'Stores a reference to any Benchling object or schema that is identified by a resource

        ID. The type field identifies what kind of resource is referenced, matching the

        BenchlingAppType values used in app manifests. Covers all linked resource types except

        EntitySchema (which has a subtype) and array elements.'
      properties:
        __typename:
          type: string
        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
        value:
          type:
          - 'null'
          - string
      type: object
    BooleanAppConfigValue:
      description: Stores a boolean value in an app configuration field.
      properties:
        __typename:
          type: string
        value:
          type:
          - 'null'
          - boolean
      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
    FloatAppConfigValue:
      description: Stores a floating-point number value in an app configuration field.
      properties:
        __typename:
          type: string
        value:
          type:
          - 'null'
          - number
      type: object
  securitySchemes:
    basicApiKeyAuth:
      description: Use issued API key for standard access to the API
      scheme: basic
      type: http
    basicClientIdSecretAuth:
      description: Auth used as part of client credentials OAuth flow prior to receiving a bearer token.
      scheme: basic
      type: http
    oAuth:
      description: OAuth2 Client Credentials flow intended for service access
      flows:
        clientCredentials:
          scopes: {}
          tokenUrl: /oauth/token
      type: oauth2