Element Biosciences Instrument Service API

openapi: 3.2.0
info:
  title: Element Biosciences Cloud Instrument Service API
  description: 'The Element Biosciences Cloud API provides programmatic access to data in

    the Element Biosciences Cloud platform: instrument runs (sequencing and

    multiomics), workflow executions, registered instruments, storage

    connections, and the files those resources produce.


    All paths are versioned under `/v1`.


    ## Authentication

    Every request must include an API key in the `x-api-key` header. Create and

    manage keys in the Element Biosciences Cloud console. Call `GET /v1/auth` to

    confirm which tenant a key belongs to.


    ## Scopes

    Each API key carries one or more scopes of the form

    `resource:action[:resource_id]`, for example `runs:read`,

    `executions:download`, or `storage:download:{connection_id}`. A request that

    is authenticated but lacks the required scope fails with HTTP 403 and the

    `INSUFFICIENT_SCOPE` reason. List endpoints transparently restrict results

    to the resources a key is scoped to.


    ## Pagination

    List endpoints are cursor-paginated. Set `page_size` to control the page

    length and pass the `next_page_token` from one response as the `page_token`

    of the next; an empty `next_page_token` indicates the last page.


    ## Errors

    Errors return a JSON body with an integer `code`, a human-readable

    `message`, and a `details` array. Each detail carries a machine-readable

    `reason` (for example `RUN_NOT_FOUND` or `INVALID_API_KEY`) and the

    `domain` `cloud-api.elembio.io`. The `request_id` in the detail metadata

    matches the `X-Request-ID` response header; include it when reporting

    problems.

    '
  version: 1.0.0
  contact:
    name: Element Biosciences
    url: https://www.elembio.io
servers:
- url: https://cloud-api.usw2.elembio.io
security:
- apiKey: []
tags:
- name: InstrumentService
  description: "InstrumentService provides access to instruments registered to the\n authenticated tenant. Requires the \"instruments:read\" scope."
paths:
  /v1/instruments:
    get:
      tags:
      - InstrumentService
      summary: ListInstruments
      description: List instruments registered to the authenticated tenant.
      operationId: InstrumentService_ListInstruments
      parameters:
      - name: pageSize
        in: query
        description: "Maximum number of instruments to return. Defaults to 100; values above\n 1000 are capped at 1000."
        schema:
          type: integer
          title: page_size
          format: int32
          description: "Maximum number of instruments to return. Defaults to 100; values above\n 1000 are capped at 1000."
      - name: pageToken
        in: query
        description: "Pagination token from a previous response's next_page_token. Omit to\n request the first page."
        schema:
          type: string
          title: page_token
          description: "Pagination token from a previous response's next_page_token. Omit to\n request the first page."
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/elembio.cloud.v1.ListInstrumentsResponse'
        '400':
          description: Bad request — the request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — the API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — the API key lacks the required scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found — the requested resource does not exist or is not accessible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
  /v1/instruments/{serial_number}:
    get:
      tags:
      - InstrumentService
      summary: GetInstrument
      description: Get a single instrument by its serial number.
      operationId: InstrumentService_GetInstrument
      parameters:
      - name: serial_number
        in: path
        description: 'Serial number of the instrument to retrieve. Example: "AV223501".'
        required: true
        schema:
          type: string
          title: serial_number
          description: 'Serial number of the instrument to retrieve. Example: "AV223501".'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/elembio.cloud.v1.GetInstrumentResponse'
        '400':
          description: Bad request — the request was malformed or a parameter was invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '401':
          description: Unauthorized — the API key is missing or invalid.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '403':
          description: Forbidden — the API key lacks the required scope.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '404':
          description: Not found — the requested resource does not exist or is not accessible.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
        '500':
          description: Internal server error.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error'
components:
  schemas:
    google.protobuf.Timestamp:
      type: string
      examples:
      - '2023-01-15T01:30:15.01Z'
      - '2024-12-25T12:00:00Z'
      format: date-time
      description: "A Timestamp represents a point in time independent of any time zone or local\n calendar, encoded as a count of seconds and fractions of seconds at\n nanosecond resolution. The count is relative to an epoch at UTC midnight on\n January 1, 1970, in the proleptic Gregorian calendar which extends the\n Gregorian calendar backwards to year one.\n\n All minutes are 60 seconds long. Leap seconds are \"smeared\" so that no leap\n second table is needed for interpretation, using a [24-hour linear\n smear](https://developers.google.com/time/smear).\n\n The range is from 0001-01-01T00:00:00Z to 9999-12-31T23:59:59.999999999Z. By\n restricting to that range, we ensure that we can convert to and from [RFC\n 3339](https://www.ietf.org/rfc/rfc3339.txt) date strings.\n\n # Examples\n\n Example 1: Compute Timestamp from POSIX `time()`.\n\n     Timestamp timestamp;\n     timestamp.set_seconds(time(NULL));\n     timestamp.set_nanos(0);\n\n Example 2: Compute Timestamp from POSIX `gettimeofday()`.\n\n     struct timeval tv;\n     gettimeofday(&tv, NULL);\n\n     Timestamp timestamp;\n     timestamp.set_seconds(tv.tv_sec);\n     timestamp.set_nanos(tv.tv_usec * 1000);\n\n Example 3: Compute Timestamp from Win32 `GetSystemTimeAsFileTime()`.\n\n     FILETIME ft;\n     GetSystemTimeAsFileTime(&ft);\n     UINT64 ticks = (((UINT64)ft.dwHighDateTime) << 32) | ft.dwLowDateTime;\n\n     // A Windows tick is 100 nanoseconds. Windows epoch 1601-01-01T00:00:00Z\n     // is 11644473600 seconds before Unix epoch 1970-01-01T00:00:00Z.\n     Timestamp timestamp;\n     timestamp.set_seconds((INT64) ((ticks / 10000000) - 11644473600LL));\n     timestamp.set_nanos((INT32) ((ticks % 10000000) * 100));\n\n Example 4: Compute Timestamp from Java `System.currentTimeMillis()`.\n\n     long millis = System.currentTimeMillis();\n\n     Timestamp timestamp = Timestamp.newBuilder().setSeconds(millis / 1000)\n         .setNanos((int) ((millis % 1000) * 1000000)).build();\n\n Example 5: Compute Timestamp from Java `Instant.now()`.\n\n     Instant now = Instant.now();\n\n     Timestamp timestamp =\n         Timestamp.newBuilder().setSeconds(now.getEpochSecond())\n             .setNanos(now.getNano()).build();\n\n Example 6: Compute Timestamp from current time in Python.\n\n     timestamp = Timestamp()\n     timestamp.GetCurrentTime()\n\n # JSON Mapping\n\n In JSON format, the Timestamp type is encoded as a string in the\n [RFC 3339](https://www.ietf.org/rfc/rfc3339.txt) format. That is, the\n format is \"{year}-{month}-{day}T{hour}:{min}:{sec}[.{frac_sec}]Z\"\n where {year} is always expressed using four digits while {month}, {day},\n {hour}, {min}, and {sec} are zero-padded to two digits each. The fractional\n seconds, which can go up to 9 digits (i.e. up to 1 nanosecond resolution),\n are optional. The \"Z\" suffix indicates the timezone (\"UTC\"); the timezone\n is required. A ProtoJSON serializer should always use UTC (as indicated by\n \"Z\") when printing the Timestamp type and a ProtoJSON parser should be\n able to accept both UTC and other timezones (as indicated by an offset).\n\n For example, \"2017-01-15T01:30:15.01Z\" encodes 15.01 seconds past\n 01:30 UTC on January 15, 2017.\n\n In JavaScript, one can convert a Date object to this format using the\n standard\n [toISOString()](https://developer.mozilla.org/en-US/docs/Web/JavaScript/Reference/Global_Objects/Date/toISOString)\n method. In Python, a standard `datetime.datetime` object can be converted\n to this format using\n [`strftime`](https://docs.python.org/2/library/time.html#time.strftime) with\n the time format spec '%Y-%m-%dT%H:%M:%S.%fZ'. Likewise, in Java, one can use\n the Joda Time's [`ISODateTimeFormat.dateTime()`](\n http://joda-time.sourceforge.net/apidocs/org/joda/time/format/ISODateTimeFormat.html#dateTime()\n ) to obtain a formatter capable of generating timestamps in this format."
    elembio.cloud.v1.InstrumentStatus:
      type: string
      title: InstrumentStatus
      enum:
      - INSTRUMENT_STATUS_UNSPECIFIED
      - INSTRUMENT_STATUS_ACTIVE
      - INSTRUMENT_STATUS_INACTIVE
      - INSTRUMENT_STATUS_DECOMMISSIONED
      description: Status of an instrument.
    elembio.cloud.v1.GetInstrumentResponse:
      type: object
      properties:
        instrument:
          title: instrument
          $ref: '#/components/schemas/elembio.cloud.v1.Instrument'
      title: GetInstrumentResponse
      additionalProperties: false
      description: Response containing a single instrument.
    ErrorDetail:
      type: object
      description: Structured error detail with a machine-readable reason code.
      properties:
        '@type':
          type: string
          description: Type identifier for this error detail
        reason:
          type: string
          description: 'Machine-readable error code identifying the specific failure

            (e.g. RUN_NOT_FOUND, INVALID_API_KEY, INSUFFICIENT_SCOPE).

            '
          examples:
          - RUN_NOT_FOUND
          - INVALID_API_KEY
          - MISSING_API_KEY
          - INSUFFICIENT_SCOPE
          - INTERNAL_ERROR
        domain:
          type: string
          description: Identifies the system that generated the error
          const: cloud-api.elembio.io
        metadata:
          type: object
          description: Additional context for the error
          properties:
            request_id:
              type: string
              description: Request ID matching the X-Request-ID response header
      required:
      - reason
      - domain
    elembio.cloud.v1.Instrument:
      type: object
      properties:
        serialNumber:
          type: string
          title: serial_number
          description: 'Serial number that uniquely identifies the instrument. Example: "AV223501".'
        name:
          type: string
          title: name
          description: Human-readable name assigned to the instrument, if any.
        model:
          type: string
          title: model
          description: "Instrument model. Possible values: \"AVITI\", \"VITARI\". Empty when the\n model is unknown."
        status:
          title: status
          description: Current operational status of the instrument.
          $ref: '#/components/schemas/elembio.cloud.v1.InstrumentStatus'
        timeCreated:
          title: time_created
          description: When the instrument was first registered.
          $ref: '#/components/schemas/google.protobuf.Timestamp'
        timeUpdated:
          title: time_updated
          description: When the instrument record was last updated.
          $ref: '#/components/schemas/google.protobuf.Timestamp'
        timeLastConnected:
          oneOf:
          - $ref: '#/components/schemas/google.protobuf.Timestamp'
          - type: 'null'
          title: time_last_connected
          description: When the instrument was last connected to the cloud, if known.
        softwareVersion:
          type:
          - string
          - 'null'
          title: software_version
          description: Software version currently installed on the instrument (AOS version).
      title: Instrument
      additionalProperties: false
      description: An Instrument represents a registered sequencing or multiomics device.
    Error:
      type: object
      description: Error response returned by all endpoints when a request fails.
      properties:
        code:
          type: integer
          description: Numeric status code corresponding to the HTTP response status
        message:
          type: string
          description: Human-readable error message
        details:
          type: array
          description: Structured error details with machine-readable reason codes
          items:
            $ref: '#/components/schemas/ErrorDetail'
      required:
      - code
      - message
      examples:
      - code: 404
        message: Run not found.
        details:
        - reason: RUN_NOT_FOUND
          domain: cloud-api.elembio.io
          metadata:
            request_id: 550e8400-e29b-41d4-a716-446655440000
      - code: 401
        message: Invalid API key.
        details:
        - reason: INVALID_API_KEY
          domain: cloud-api.elembio.io
          metadata:
            request_id: 550e8400-e29b-41d4-a716-446655440001
    elembio.cloud.v1.ListInstrumentsResponse:
      type: object
      properties:
        instruments:
          type: array
          items:
            $ref: '#/components/schemas/elembio.cloud.v1.Instrument'
          title: instruments
          description: The instruments on this page.
        nextPageToken:
          type: string
          title: next_page_token
          description: Token for the next page, or empty when there are no more results.
      title: ListInstrumentsResponse
      additionalProperties: false
      description: Response containing a page of instruments.
  securitySchemes:
    apiKey:
      type: apiKey
      in: header
      name: x-api-key
      description: API key obtained from the Element Biosciences Cloud console