openapi: 3.2.0
info:
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Benchling Well Plate Position API
  version: 2.0.0
  description: 'Represents a single well within a WellPlate, functioning as a fixed container at a

    specific grid position. Each WellPlatePosition has coordinates identifying its row

    and column, can hold sample contents (see ContainerContent), and tracks quantity as

    a Measurement. Wells can be assigned an ExperimentalRole for assay organization and

    support freeze/thaw tracking (see FreezeThawInfo) and expiration tracking (see

    ExpirationInfo) when enabled on the well''s ContainerSchema. Unlike containers in a

    MatrixPlate, WellPlatePositions are permanent parts of the plate structure and cannot

    be removed or repositioned. Wells are accessed through the parent WellPlate''s positions

    field.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'Represents a single well within a WellPlate, functioning as a fixed container at a

    specific grid position. Each WellPlatePosition has coordinates identifying its row

    and column, can hold sample contents (see ContainerContent), and tracks quantity as

    a Measurement. Wells can be assigned an ExperimentalRole for assay organization and

    support freeze/thaw tracking (see FreezeThawInfo) and expiration tracking (see

    ExpirationInfo) when enabled on the well''s ContainerSchema. Unlike containers in a

    MatrixPlate, WellPlatePositions are permanent parts of the plate structure and cannot

    be removed or repositioned. Wells are accessed through the parent WellPlate''s positions

    field.'
  name: WellPlatePosition
  x-bnch-organization: Benchling
paths:
  /well-plate-position/items:
    get:
      description: List WellPlatePosition items.
      operationId: WellPlatePosition.List
      parameters:
      - $ref: '#/components/parameters/createdAt.gt'
      - $ref: '#/components/parameters/createdAt.gte'
      - $ref: '#/components/parameters/createdAt.lt'
      - $ref: '#/components/parameters/createdAt.lte'
      - $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/WellPlatePositionPaginatedList'
          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 WellPlatePosition items
      tags:
      - WellPlatePosition
      x-bnch-rate-limit-tier: 4
  /well-plate-position/{well_plate_position_id}:
    get:
      description: Get a single WellPlatePosition by ID.
      operationId: WellPlatePosition.Get
      parameters:
      - description: ID of the WellPlatePosition.
        in: path
        name: well_plate_position_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/WellPlatePosition'
          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 WellPlatePosition by ID
      tags:
      - WellPlatePosition
      x-bnch-rate-limit-tier: 5
components:
  schemas:
    GridCoordinates:
      description: Read model representing a fillable position in a box or plate.
      properties:
        __typename:
          type: string
        column:
          description: The 0-indexed column index of the position
          type: integer
        index:
          description: 'The 1-indexed position determined by counting across rows.

            For example, for a six-well plate:

            +---+---+---+

            | 1 | 2 | 3 |

            +---+---+---+

            | 4 | 5 | 6 |

            +---+---+---+'
          type: integer
        position:
          description: 'The alphanumeric position, where rows are indexed alphabetically and columns are indexed numerically,

            starting from "A1"'
          type: string
        row:
          description: The 0-indexed row index of the position
          type: integer
      type: object
    WellPlatePosition:
      description: 'Represents a single well within a WellPlate, functioning as a fixed container at a

        specific grid position. Each WellPlatePosition has coordinates identifying its row

        and column, can hold sample contents (see ContainerContent), and tracks quantity as

        a Measurement. Wells can be assigned an ExperimentalRole for assay organization and

        support freeze/thaw tracking (see FreezeThawInfo) and expiration tracking (see

        ExpirationInfo) when enabled on the well''s ContainerSchema. Unlike containers in a

        MatrixPlate, WellPlatePositions are permanent parts of the plate structure and cannot

        be removed or repositioned. Wells are accessed through the parent WellPlate''s positions

        field.'
      properties:
        __typename:
          type: string
        contents:
          description: Well contents of the well plate.
          items:
            $ref: '#/components/schemas/ContainerContent'
          type: array
        coordinates:
          $ref: '#/components/schemas/GridCoordinates'
          description: Coordinates of the current position within the well plate.
        createdAt:
          description: When the well plate was created.
          format: datetime
          type: string
        expirationInfo:
          $ref: '#/components/schemas/ExpirationInfo'
          description: Expiration info for the container.
        id:
          description: The ID of the container representing the well at this plate position.
          type: string
        modifiedAt:
          description: When the well plate was last modified.
          format: datetime
          type: string
        name:
          description: The name of the container representing the well at this position.
          type: string
        quantity:
          description: Quantity of a well. Supports mass, volume, and other quantities.
          oneOf:
          - $ref: '#/components/schemas/Measurement'
          - type: 'null'
        role:
          oneOf:
          - $ref: '#/components/schemas/ExperimentalRole'
          - type: 'null'
        schema:
          $ref: '#/components/schemas/ContainerSchemaRef'
          description: The container schema used by wells in the well plate.
      type: object
    ExperimentalRole:
      description: 'Represents the complete experimental designation of a well or container within an assay,

        combining a primary role (see PrimaryExperimentalRole), replicate group number, and

        optional subrole. The group field identifies replicate sets: wells with the same primary

        role and group number are treated as technical replicates for statistical analysis. The

        subrole field provides additional categorization for controls (e.g., POSITIVE, NEGATIVE,

        MAXIMUM, MINIMUM); only CONTROL primary roles may have subroles. ExperimentalRole is

        used in plate-based workflows to define experimental layouts (see PlateMapPosition) and

        annotate wells in FixedPlate and Container objects.'
      properties:
        __typename:
          type: string
        group:
          description: Role group (aka replicate id)
          type: integer
        primaryRole:
          description: Primary role
          enum:
          - CONTROL
          - SAMPLE
          - BLANK
          - STANDARD
          type: string
        subrole:
          description: Subrole, used to differentiate different sub types of a role (e.g. positive control)
          type:
          - 'null'
          - string
      type: object
    WellPlatePositionPaginatedList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/WellPlatePosition'
          type: array
        nextToken:
          type: 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
    ContainerContent:
      description: 'Represents a biological or chemical entity stored within a Container or well. Each

        ContainerContent links an Entity (such as a DNA sequence, protein, or custom entity)

        to its storage location, along with an optional concentration measurement. The

        timestamps track when the entity was first placed in the container and when the

        concentration was last modified. A container can hold multiple ContainerContent

        items representing different entities or samples stored together.'
      properties:
        __typename:
          type: string
        concentration:
          description: Concentration of the entity in the container.
          oneOf:
          - $ref: '#/components/schemas/Measurement'
          - type: 'null'
        createdAt:
          description: When the container was first filled with this entity.
          format: datetime
          type: string
        entity:
          description: The entity in the container.
          oneOf:
          - $ref: '#/components/schemas/EntityRef'
          - type: 'null'
        modifiedAt:
          description: When the entity was last added to this container or the concentration was last changed.
          format: datetime
          type: string
      type: object
    Measurement:
      description: 'Represents a quantity with an associated unit of measurement within Benchling''s inventory

        system. Measurements are used throughout inventory to track container volumes, sample

        masses, concentrations, and other quantitative values. Each Measurement pairs a numeric

        value with a Unit (see Unit) to provide context-aware quantity handling. For example,

        a container might have a Measurement of 500 uL for its volume. Unlike ContainerQuantity

        which provides a simpler representation, Measurement supports the full Unit system with

        dimensional conversions.'
      properties:
        __typename:
          type: string
        unit:
          oneOf:
          - $ref: '#/components/schemas/UnitRef'
          - type: 'null'
        value:
          type:
          - 'null'
          - number
      type: object
    ExpirationInfo:
      description: 'Provides expiration tracking for inventory items such as containers and their

        contents. The expirationDate may be explicitly set on the container or inherited

        from the stored entity''s properties. The isExpired flag is a computed convenience

        field that returns true if the current date is past the expiration date. Items

        without an expiration date are considered non-expiring (isExpired returns false).'
      properties:
        __typename:
          type: string
        expirationDate:
          description: Expiration date of the item, potentially inherited from the contents or overridden.
          format: datetime
          type:
          - 'null'
          - string
        isExpired:
          description: Whether the item is past its expiration date. Items without an expiration date return False.
          type: boolean
      type: object
    ContainerSchemaRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      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
    UnitRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    EntityRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
  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
    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
    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
    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
  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