openapi: 3.2.0
info:
  license:
    name: Apache 2.0
    url: http://www.apache.org/licenses/LICENSE-2.0.html
  title: Benchling Run API
  version: 2.0.0
  description: 'A Run represents an execution instance of a lab automation workflow in Benchling, capturing

    the inputs, outputs, and metadata for a single assay or instrument operation. Runs conform

    to a RunSchema that defines their structure including input generators (see AutomationInputGenerator)

    for creating worklists and output processors (see AutomationOutputProcessor) for parsing

    instrument results. Runs are typically embedded in notebook entries (via the entry field)

    and can generate associated Analyses for data processing. Each run tracks validation status

    (VALID or INVALID) with optional comments, enabling quality control workflows. Runs belong

    to a Project for access control and can be archived when superseded or invalidated. Also

    known as "assay runs" in the lab automation context.'
servers:
- url: /api/v3
security:
- oAuth: []
- basicApiKeyAuth: []
tags:
- description: 'A Run represents an execution instance of a lab automation workflow in Benchling, capturing

    the inputs, outputs, and metadata for a single assay or instrument operation. Runs conform

    to a RunSchema that defines their structure including input generators (see AutomationInputGenerator)

    for creating worklists and output processors (see AutomationOutputProcessor) for parsing

    instrument results. Runs are typically embedded in notebook entries (via the entry field)

    and can generate associated Analyses for data processing. Each run tracks validation status

    (VALID or INVALID) with optional comments, enabling quality control workflows. Runs belong

    to a Project for access control and can be archived when superseded or invalidated. Also

    known as "assay runs" in the lab automation context.'
  name: Run
  x-bnch-core-type: Run
  x-bnch-organization: Benchling
paths:
  /run/items:
    get:
      description: List Run items.
      operationId: Run.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/nextToken'
      - $ref: '#/components/parameters/omit'
      - $ref: '#/components/parameters/pageSize'
      - $ref: '#/components/parameters/returning'
      - $ref: '#/components/parameters/schema.anyOf'
      - $ref: '#/components/parameters/schema.eq'
      - 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/RunPaginatedList'
          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 Run items
      tags:
      - Run
      x-bnch-rate-limit-tier: 4
  /run/{run_id}:
    get:
      description: Get a single Run by ID.
      operationId: Run.Get
      parameters:
      - description: ID of the Run.
        in: path
        name: run_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/Run'
          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 Run by ID
      tags:
      - Run
      x-bnch-rate-limit-tier: 5
webhooks:
  v3.run.created:
    post:
      description: Sent to Benchling Apps subscribed to `v3.run.created` when a Run they can access is created.
      operationId: Run.Created
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/RunCreatedWebhookEnvelopeV3'
        description: The `v3.run.created` event.
        required: true
      responses:
        '200':
          description: Return a 200 status code to acknowledge receipt of the webhook.
      summary: Run created
      tags:
      - Run
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
    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
    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
    schema.anyOf:
      description: Restricts results to those that match any of the specified schema IDs. Use only one `schema` filter arg at a time. Comma-separated list.
      explode: false
      in: query
      name: schema.anyOf
      schema:
        items:
          type: string
        maxItems: 100
        type: array
    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
    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
    schema.eq:
      description: Single schema ID. Restricts results to those that match the specified schema exactly. Use only one `schema` filter arg at a time.
      in: query
      name: schema.eq
      schema:
        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
  schemas:
    IRun:
      properties:
        __typename:
          type: string
        archiveReason:
          description: If the Run is archived, reason for archiving
          type:
          - 'null'
          - string
        archived:
          description: Whether the Run is archived
          type: boolean
        createdAt:
          description: DateTime at which the run was created
          format: datetime
          type:
          - 'null'
          - string
        id:
          type: string
        isReviewed:
          description: Whether this run is in a reviewed entry
          type:
          - 'null'
          - boolean
        modifiedAt:
          description: DateTime at which the run was last modified
          format: datetime
          type:
          - 'null'
          - string
        project:
          description: Project this run is in
          oneOf:
          - $ref: '#/components/schemas/ProjectRef'
          - type: 'null'
        schema:
          description: Schema that this run belongs to
          oneOf:
          - $ref: '#/components/schemas/RunSchemaRef'
          - type: 'null'
        validationComment:
          description: Comment for this run's validation status
          type:
          - 'null'
          - string
        validationStatus:
          description: Validation status of this run - must be either VALID or INVALID
          enum:
          - VALID
          - INVALID
          - null
          type:
          - 'null'
          - string
      type: object
    DateValue:
      description: A type that represents date values.
      properties:
        __typename:
          type: string
        value:
          description: The date value.
          format: date
          type: string
      type: object
    BooleanValue:
      description: A type that represents boolean values.
      properties:
        __typename:
          type: string
        value:
          description: The boolean value.
          type: boolean
      type: object
    WebhookApp:
      description: The Benchling App the webhook was delivered to.
      properties:
        id:
          description: API ID of the app.
          examples:
          - app_1jdbvuo2740aslk
          type: string
      required:
      - id
      type: object
    ProjectRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    ObjectLinkValue:
      description: A type that represents links to other objects.
      properties:
        __typename:
          type: string
        value:
          $ref: '#/components/schemas/ObjectRef'
          description: The object that this value links to, or an Inaccessible object if not found with the current permission set.
      type: object
    RunSchemaRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    SchemaFieldValue:
      description: 'Represents a field value on a schematized object, pairing a `fieldDefinition` (describing the

        field''s type and constraints) with its actual `value` (a `BenchlingValue` such as text, number,

        date, or link to another object). The value may be null if no value has been set. Used within

        the `schemaFields` collection on objects that implement `HasSchema` to provide access to all

        custom field values defined by the object''s schema.'
      properties:
        __typename:
          type: string
        fieldDefinition:
          $ref: '#/components/schemas/SchemaFieldDefinitionRef'
        id:
          type: string
        linkedEntityId:
          type:
          - 'null'
          - string
        value:
          description: Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue, ArrayValue
          oneOf:
          - anyOf:
            - $ref: '#/components/schemas/BooleanValue'
            - $ref: '#/components/schemas/DateTimeValue'
            - $ref: '#/components/schemas/DateValue'
            - $ref: '#/components/schemas/DecimalValue'
            - $ref: '#/components/schemas/IntegerValue'
            - $ref: '#/components/schemas/JsonValue'
            - $ref: '#/components/schemas/ObjectLinkValue'
            - $ref: '#/components/schemas/ObjectLinkListValue'
            - $ref: '#/components/schemas/TextAndUrlValue'
            - $ref: '#/components/schemas/TextValue'
            - $ref: '#/components/schemas/ArrayValue'
            discriminator:
              propertyName: __typename
          - type: 'null'
      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
    DecimalValue:
      description: A type that represents decimal value as strings.
      properties:
        __typename:
          type: string
        numericValue:
          deprecated: true
          description: Deprecated. The float representation of the decimal value.
          type:
          - 'null'
          - number
        value:
          description: The decimal value in a string representation
          type:
          - 'null'
          - string
      type: object
    ArrayValue:
      description: A type that represents a list of BenchlingValues, used for multi-value cells (e.g. alias columns).
      properties:
        __typename:
          type: string
        value:
          items:
            anyOf:
            - $ref: '#/components/schemas/BooleanValue'
            - $ref: '#/components/schemas/DateTimeValue'
            - $ref: '#/components/schemas/DateValue'
            - $ref: '#/components/schemas/DecimalValue'
            - $ref: '#/components/schemas/IntegerValue'
            - $ref: '#/components/schemas/JsonValue'
            - $ref: '#/components/schemas/ObjectLinkValue'
            - $ref: '#/components/schemas/ObjectLinkListValue'
            - $ref: '#/components/schemas/TextAndUrlValue'
            - $ref: '#/components/schemas/TextValue'
            description: Union of BooleanValue, DateTimeValue, DateValue, DecimalValue, IntegerValue, JsonValue, ObjectLinkValue, ObjectLinkListValue, TextAndUrlValue, TextValue
            discriminator:
              propertyName: __typename
          type: array
      type: object
    RunCreatedWebhookV3:
      allOf:
      - $ref: '#/components/schemas/V3EventBase'
      - properties:
          type:
            description: The event type.
            enum:
            - v3.run.created
            type: string
        required:
        - type
        type: object
      description: Message body of a `v3.run.created` event.
    WebhookAppDefinition:
      description: The app definition the receiving app was installed from.
      properties:
        id:
          description: API ID of the app definition.
          examples:
          - appdef_1jdbvuo2740aslk
          type:
          - 'null'
          - string
        versionNumber:
          description: Version of the app definition the receiving app is installed at.
          examples:
          - 0.0.1
          type: string
      required:
      - id
      - versionNumber
      type: object
    RunCreatedWebhookEnvelopeV3:
      allOf:
      - $ref: '#/components/schemas/WebhookEnvelopeBaseV0'
      - properties:
          message:
            $ref: '#/components/schemas/RunCreatedWebhookV3'
        required:
        - message
        type: object
      description: Request body Benchling sends for a `v3.run.created` event.
    PrincipalRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    DocumentLikeRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    DateTimeValue:
      description: A type that represents datetime values.
      properties:
        __typename:
          type: string
        value:
          description: The datetime value with UTC as the timezone.
          format: datetime
          type: string
      type: object
    RunPaginatedList:
      additionalProperties: false
      properties:
        items:
          items:
            $ref: '#/components/schemas/Run'
          type: array
        nextToken:
          type: string
      type: object
    ObjectRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    Run:
      allOf:
      - $ref: '#/components/schemas/IRun'
      - description: 'A Run represents an execution instance of a lab automation workflow in Benchling, capturing

          the inputs, outputs, and metadata for a single assay or instrument operation. Runs conform

          to a RunSchema that defines their structure including input generators (see AutomationInputGenerator)

          for creating worklists and output processors (see AutomationOutputProcessor) for parsing

          instrument results. Runs are typically embedded in notebook entries (via the entry field)

          and can generate associated Analyses for data processing. Each run tracks validation status

          (VALID or INVALID) with optional comments, enabling quality control workflows. Runs belong

          to a Project for access control and can be archived when superseded or invalidated. Also

          known as "assay runs" in the lab automation context.'
        properties:
          __typename:
            type: string
          creator:
            description: User who created the run
            oneOf:
            - $ref: '#/components/schemas/PrincipalRef'
            - type: 'null'
          entry:
            description: Entry that this run is attached to
            oneOf:
            - $ref: '#/components/schemas/DocumentLikeRef'
            - type: 'null'
          schemaFields:
            description: Schema field values that belong to the run
            oneOf:
            - items:
                $ref: '#/components/schemas/SchemaFieldValue'
              type: array
            - type: 'null'
        type: object
    TextValue:
      description: A type that represents text (string) values.
      properties:
        __typename:
          type: string
        value:
          description: The text value. It may or may not be an empty string.
          type: string
      type: object
    V3EventBase:
      description: Fields common to every v3 event message.
      properties:
        createdAt:
          description: RFC 3339 timestamp of when the event was created.
          format: date-time
          type: string
        deprecated:
          description: Whether this event type is deprecated.
          type: boolean
        id:
          description: API ID of the event.
          examples:
          - evt_1jdbvuo2740aslk
          type: string
        resourceId:
          description: API ID of the resource the event is about.
          examples:
          - seq_1jdbvuo2740aslk
          type: string
        stability:
          description: Stability of the resource type the event is about.
          enum:
          - stable
          - beta
          type: string
        type:
          description: The event type.
          examples:
          - v3.dnaSequence.created
          type: string
      required:
      - id
      - type
      - createdAt
      - resourceId
      - stability
      - deprecated
      type: object
    JsonValue:
      description: A type that represents JSON values.
      properties:
        __typename:
          type: string
        value:
          description: The JSON value.
          type: object
      type: object
    TextAndUrlValue:
      description: A type that represents text (string) values with an associated URL.
      properties:
        __typename:
          type: string
        url:
          description: The URL associated with the value. Please use `TextValue` if you don't want a URL.
          type: string
        value:
          description: The text value. It may or may not be an empty string.
          type: string
      type: object
    IntegerValue:
      description: A type that represents integer values.
      properties:
        __typename:
          type: string
        value:
          description: The integer value.
          type: integer
      type: object
    SchemaFieldDefinitionRef:
      properties:
        __typename:
          type: string
        id:
          format: api_id
          type: string
      type: object
    ObjectLinkListValue:
      description: A type that represents a list of links to other objects.
      properties:
        __typename:
          type: string
        value:
          description: The list of objects that this value links to. Inaccessible objects may be returned instead if the object is not found with the current permission set.
          items:
            $ref: '#/components/schemas/ObjectRef'
            description: Union of AaSequence, Box, Container, CustomEntity, DnaSequence, DropdownOption, Entry, Location, Mixture, Molecule, Plate, Result, RnaSequence, Run, DnaOligo, RnaOligo
          type: array
      type: object
    WebhookEnvelopeBaseV0:
      description: Fields common to every webhook request body. The event itself is carried in the `message` property of the event-specific payload.
      properties:
        app:
          $ref: '#/components/schemas/WebhookApp'
        appDefinition:
          $ref: '#/components/schemas/WebhookAppDefinition'
        baseURL:
          description: Base URL of the tenant the webhook was sent from.
          examples:
          - https://mytenant.benchling.com
          type: string
        tenantId:
          description: Global ID of the tenant the webhook was sent from.
          examples:
          - ten_7fbo183
          type: string
        version:
          description: Version of the webhook envelope shape. Always `0`.
          enum:
          - '0'
          type: string
      required:
      - version
      - baseURL
      - tenantId
      - app
      - appDefinition
      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
  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