openapi: 3.2.0
info:
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Benchling Dropdown API
  version: 2.0.0
  description: 'A configurable list of predefined values used for standardizing data entry in schema fields.

    Dropdowns provide controlled vocabulary choices that ensure consistency when users fill out

    entity and object fields. Each Dropdown belongs to a Registry (see `registry`) and contains

    one or more selectable options (see `DropdownOption`). Dropdowns are referenced by schema

    field definitions (see `DropdownLinkFieldDefinition`) to constrain the allowed values for a

    field. Organizations use dropdowns to enforce standardized terminology across experiments,

    samples, and other registered entities.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A configurable list of predefined values used for standardizing data entry in schema fields.

    Dropdowns provide controlled vocabulary choices that ensure consistency when users fill out

    entity and object fields. Each Dropdown belongs to a Registry (see `registry`) and contains

    one or more selectable options (see `DropdownOption`). Dropdowns are referenced by schema

    field definitions (see `DropdownLinkFieldDefinition`) to constrain the allowed values for a

    field. Organizations use dropdowns to enforce standardized terminology across experiments,

    samples, and other registered entities.'
  name: Dropdown
  x-bnch-organization: Benchling
paths:
  /dropdown:
    post:
      description: Create Dropdown.
      operationId: Dropdown.Create
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDropdownInput'
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dropdown'
          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 Dropdown
      tags:
      - Dropdown
      x-bnch-rate-limit-tier: 4
  /dropdown/items:
    get:
      description: List Dropdown items.
      operationId: Dropdown.List
      parameters:
      - $ref: '#/components/parameters/archiveReason.anyOf'
      - $ref: '#/components/parameters/archived.anyOf'
      - $ref: '#/components/parameters/id.anyOf'
      - $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'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DropdownPaginatedList'
          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 Dropdown items
      tags:
      - Dropdown
      x-bnch-rate-limit-tier: 4
  /dropdown/{dropdown_id}:
    get:
      description: Get a single Dropdown by ID.
      operationId: Dropdown.Get
      parameters:
      - description: ID of the Dropdown.
        in: path
        name: dropdown_id
        required: true
        schema:
          type: string
      - $ref: '#/components/parameters/returning'
      - $ref: '#/components/parameters/omit'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dropdown'
          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 Dropdown by ID
      tags:
      - Dropdown
      x-bnch-rate-limit-tier: 5
    patch:
      description: Update Dropdown.
      operationId: Dropdown.Update
      parameters:
      - description: ID of the Dropdown.
        in: path
        name: dropdown_id
        required: true
        schema:
          type: string
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/UpdateDropdownInput'
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Dropdown'
          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 Dropdown
      tags:
      - Dropdown
      x-bnch-rate-limit-tier: 4
  /dropdown/{dropdown_id}/options/items:
    get:
      description: List DropdownOption items.
      operationId: Dropdown.options.List
      parameters:
      - description: ID of the Dropdown.
        in: path
        name: dropdown_id
        required: true
        schema:
          type: string
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DropdownOptionUnpaginatedList'
          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 DropdownOption items
      tags:
      - Dropdown
      x-bnch-rate-limit-tier: 4
  /dropdown:batch-create:
    post:
      description: Batch create Dropdown synchronously in one transaction. Maximum 25 items per request.
      operationId: Dropdown.BatchCreate
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                items:
                  items:
                    $ref: '#/components/schemas/CreateDropdownInput'
                  maxItems: 25
                  minItems: 1
                  type: array
              required:
              - items
              type: object
      responses:
        '201':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/Dropdown'
                    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 Dropdown
      tags:
      - Dropdown
      x-bnch-rate-limit-tier: 3
  /dropdown:batch-update:
    patch:
      description: Batch update Dropdown synchronously in one transaction. Maximum 25 items per request.
      operationId: Dropdown.BatchUpdate
      requestBody:
        content:
          application/json:
            schema:
              additionalProperties: false
              properties:
                items:
                  items:
                    $ref: '#/components/schemas/UpdateDropdownInputWithPathParams'
                  maxItems: 25
                  minItems: 1
                  type: array
              required:
              - items
              type: object
      responses:
        '200':
          content:
            application/json:
              schema:
                additionalProperties: false
                properties:
                  items:
                    items:
                      $ref: '#/components/schemas/Dropdown'
                    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 Dropdown
      tags:
      - Dropdown
      x-bnch-rate-limit-tier: 3
  /dropdown:bulk-create:
    post:
      description: Bulk create Dropdown.
      operationId: Dropdown.BulkCreate
      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 Dropdown
      tags:
      - Dropdown
      x-bnch-rate-limit-tier: 2
  /dropdown:bulk-update:
    patch:
      description: Bulk update Dropdown.
      operationId: Dropdown.BulkUpdate
      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 Dropdown
      tags:
      - Dropdown
      x-bnch-rate-limit-tier: 2
components:
  parameters:
    pageSize:
      description: Number of results to return. Defaults to 50, maximum of 100.
      in: query
      name: pageSize
      schema:
        type: integer
    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
    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
    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
  schemas:
    UpdateDropdownOptionInput:
      additionalProperties: false
      properties:
        archiveReason:
          type: string
        archived:
          type: boolean
        id:
          type: string
        name:
          type: string
      required:
      - id
      type: object
    DropdownOption:
      description: 'An individual selectable value within a Dropdown. Each DropdownOption represents one valid

        choice that users can select when populating a schema field configured with the parent

        Dropdown. Options can be archived to remove them from the available choices while preserving

        historical data that references them. The option''s name is displayed to users when selecting

        values.'
      properties:
        __typename:
          type: string
        archiveReason:
          type:
          - 'null'
          - string
        archived:
          type: boolean
        id:
          type: string
        name:
          type: string
      type: object
    DropdownPaginatedList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/Dropdown'
          type: array
        nextToken:
          type: string
      type: object
    UpdateDropdownInput:
      additionalProperties: false
      properties:
        archiveReason:
          type: string
        archived:
          type: boolean
        name:
          description: Name of the dropdown
          type: string
        options:
          description: Array of dropdown options
          items:
            anyOf:
            - $ref: '#/components/schemas/CreateDropdownOptionInput'
            - $ref: '#/components/schemas/UpdateDropdownOptionInput'
          type: array
      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
    AsyncTaskLink:
      properties:
        pollingUri:
          format: uri
          type: string
        taskId:
          type: string
      type: object
    UpdateDropdownInputWithPathParams:
      additionalProperties: false
      properties:
        archiveReason:
          type: string
        archived:
          type: boolean
        id:
          type: string
        name:
          description: Name of the dropdown
          type: string
        options:
          description: Array of dropdown options
          items:
            anyOf:
            - $ref: '#/components/schemas/CreateDropdownOptionInput'
            - $ref: '#/components/schemas/UpdateDropdownOptionInput'
          type: array
      required:
      - id
      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
    CreateDropdownOptionInput:
      additionalProperties: false
      properties:
        name:
          type: string
      required:
      - name
      type: object
    RegistryRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    Dropdown:
      description: 'A configurable list of predefined values used for standardizing data entry in schema fields.

        Dropdowns provide controlled vocabulary choices that ensure consistency when users fill out

        entity and object fields. Each Dropdown belongs to a Registry (see `registry`) and contains

        one or more selectable options (see `DropdownOption`). Dropdowns are referenced by schema

        field definitions (see `DropdownLinkFieldDefinition`) to constrain the allowed values for a

        field. Organizations use dropdowns to enforce standardized terminology across experiments,

        samples, and other registered entities.'
      properties:
        __typename:
          type: string
        archiveReason:
          type:
          - 'null'
          - string
        archived:
          type: boolean
        id:
          description: ID of the dropdown
          type: string
        name:
          description: Name of the dropdown
          type: string
        options:
          description: Array of dropdown options
          format: uri
          type: string
        registry:
          $ref: '#/components/schemas/RegistryRef'
          description: The registry that the dropdown belongs to
      type: object
    CreateDropdownInput:
      additionalProperties: false
      properties:
        name:
          description: Name of the dropdown
          type: string
        options:
          description: Array of dropdown options
          items:
            $ref: '#/components/schemas/CreateDropdownOptionInput'
          type: array
        registryId:
          type: string
      required:
      - name
      - registryId
      - options
      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
    DropdownOptionUnpaginatedList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/DropdownOption'
          type: array
      type: object
  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
  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