openapi: 3.0.3
info:
  contact:
    email: engineering@blues.io
    name: Blues Engineering
    url: https://dev.blues.io/support/
  description: 'The OpenAPI definition for the Notehub.io API.

    '
  title: Notehub alert event API
  version: 1.2.0
servers:
- description: Production server
  url: https://api.notefile.net
tags:
- description: Event retrieval operations
  name: event
paths:
  /v1/projects/{projectOrProductUID}/events:
    get:
      operationId: GetEvents
      description: Get Events of a Project
      parameters:
      - $ref: '#/components/parameters/projectOrProductUIDParam'
      - $ref: '#/components/parameters/pageSizeParam'
      - $ref: '#/components/parameters/pageNumParam'
      - $ref: '#/components/parameters/deviceUIDParamQuery'
      - $ref: '#/components/parameters/sortByParam'
      - $ref: '#/components/parameters/sortOrderParam'
      - $ref: '#/components/parameters/startDateParam'
      - $ref: '#/components/parameters/endDateParam'
      - $ref: '#/components/parameters/dateTypeParam'
      - $ref: '#/components/parameters/systemFilesOnlyParam'
      - $ref: '#/components/parameters/filesQueryParam'
      - $ref: '#/components/parameters/formatParam'
      - $ref: '#/components/parameters/serialNumberFilterParam'
      - $ref: '#/components/parameters/fleetUIDFilterQueryParam'
      - $ref: '#/components/parameters/sessionUIDFilterParam'
      - $ref: '#/components/parameters/eventUIDFilterQueryParam'
      - $ref: '#/components/parameters/selectFieldsParam'
      - name: deviceUIDs
        in: query
        description: Deprecated.
        required: false
        schema:
          type: array
          items:
            type: string
        deprecated: true
      - name: since
        in: query
        description: Deprecated.
        required: false
        schema:
          type: string
        deprecated: true
      responses:
        '200':
          $ref: '#/components/responses/EventsResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - event
      x-custom-attributes:
        permission: read
        resource: blues:resources:app:APPSERIAL:events
  /v1/projects/{projectOrProductUID}/events-cursor:
    get:
      operationId: GetEventsByCursor
      description: Get Events of a Project by cursor
      parameters:
      - $ref: '#/components/parameters/projectOrProductUIDParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/cursorParam'
      - $ref: '#/components/parameters/sortOrderParam'
      - $ref: '#/components/parameters/systemFilesOnlyParam'
      - $ref: '#/components/parameters/filesQueryParam'
      - $ref: '#/components/parameters/fleetUIDQueryParam'
      - $ref: '#/components/parameters/deviceUIDParamQuery'
      responses:
        '200':
          $ref: '#/components/responses/EventsByCursorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - event
      x-custom-attributes:
        permission: read
        resource: blues:resources:app:APPSERIAL:events
  /v1/projects/{projectOrProductUID}/events/{eventUID}/route-logs:
    get:
      operationId: GetRouteLogsByEvent
      description: Get Route Logs by Event UID
      parameters:
      - $ref: '#/components/parameters/projectOrProductUIDParam'
      - $ref: '#/components/parameters/eventUIDParam'
      responses:
        '200':
          description: Successful operation
          content:
            application/json:
              schema:
                type: array
                items:
                  $ref: '#/components/schemas/RouteLog'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - event
      x-custom-attributes:
        permission: read
        resource: blues:resources:app:APPSERIAL:events
  /v1/projects/{projectOrProductUID}/fleets/{fleetUID}/events:
    get:
      operationId: GetFleetEvents
      description: Get Events of a Fleet
      parameters:
      - $ref: '#/components/parameters/projectOrProductUIDParam'
      - $ref: '#/components/parameters/fleetUIDParam'
      - $ref: '#/components/parameters/pageSizeParam'
      - $ref: '#/components/parameters/pageNumParam'
      - $ref: '#/components/parameters/deviceUIDParamQuery'
      - $ref: '#/components/parameters/sortByParam'
      - $ref: '#/components/parameters/sortOrderParam'
      - $ref: '#/components/parameters/startDateParam'
      - $ref: '#/components/parameters/endDateParam'
      - $ref: '#/components/parameters/dateTypeParam'
      - $ref: '#/components/parameters/systemFilesOnlyParam'
      - $ref: '#/components/parameters/filesQueryParam'
      - $ref: '#/components/parameters/formatParam'
      - $ref: '#/components/parameters/serialNumberFilterParam'
      - $ref: '#/components/parameters/sessionUIDFilterParam'
      - $ref: '#/components/parameters/eventUIDFilterQueryParam'
      - $ref: '#/components/parameters/selectFieldsParam'
      - name: deviceUIDs
        in: query
        description: Deprecated.
        required: false
        schema:
          type: array
          items:
            type: string
        deprecated: true
      - name: since
        in: query
        description: Deprecated.
        required: false
        schema:
          type: string
        deprecated: true
      responses:
        '200':
          $ref: '#/components/responses/EventsResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - event
      x-custom-attributes:
        permission: read
        resource: blues:resources:app:APPSERIAL:events
  /v1/projects/{projectOrProductUID}/fleets/{fleetUID}/events-cursor:
    get:
      operationId: GetFleetEventsByCursor
      description: Get Events of a Fleet by cursor
      parameters:
      - $ref: '#/components/parameters/projectOrProductUIDParam'
      - $ref: '#/components/parameters/fleetUIDParam'
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/cursorParam'
      - $ref: '#/components/parameters/sortOrderParam'
      - $ref: '#/components/parameters/systemFilesOnlyParam'
      - $ref: '#/components/parameters/filesQueryParam'
      - $ref: '#/components/parameters/deviceUIDParamQuery'
      - $ref: '#/components/parameters/startDateParam'
      - $ref: '#/components/parameters/endDateParam'
      responses:
        '200':
          $ref: '#/components/responses/EventsByCursorResponse'
        default:
          $ref: '#/components/responses/ErrorResponse'
      security:
      - personalAccessToken: []
      tags:
      - event
      x-custom-attributes:
        permission: read
        resource: blues:resources:app:APPSERIAL:events
components:
  parameters:
    serialNumberFilterParam:
      description: Filter by Serial Number
      explode: true
      in: query
      name: serialNumber
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
    selectFieldsParam:
      description: Comma-separated list of fields to select from JSON payload (e.g., "field1,field2.subfield,field3"), this will reflect the columns in the CSV output.
      in: query
      name: selectFields
      required: false
      schema:
        type: string
    fleetUIDQueryParam:
      in: query
      name: fleetUID
      required: false
      schema:
        type: string
    sessionUIDFilterParam:
      description: Filter by Session UID
      explode: true
      in: query
      name: sessionUID
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
    startDateParam:
      description: Start date for filtering results, specified as a Unix timestamp
      example: 1628631763
      in: query
      name: startDate
      required: false
      schema:
        type: integer
        minimum: 0
    eventUIDParam:
      example: 4506f411-dea6-44a0-9743-1130f57d7747
      in: path
      name: eventUID
      required: true
      schema:
        type: string
    dateTypeParam:
      description: Which date to filter on, either 'captured' or 'uploaded'.  This will apply to the startDate and endDate parameters
      example: uploaded
      in: query
      name: dateType
      required: false
      schema:
        type: string
        default: captured
        enum:
        - captured
        - uploaded
    sortOrderParam:
      in: query
      name: sortOrder
      required: false
      schema:
        type: string
        default: asc
        enum:
        - asc
        - desc
    limitParam:
      in: query
      name: limit
      required: false
      schema:
        type: integer
        default: 50
        minimum: 1
    fleetUIDFilterQueryParam:
      description: Filter by Fleet UID
      explode: true
      in: query
      name: fleetUID
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
    pageNumParam:
      in: query
      name: pageNum
      required: false
      schema:
        type: integer
        default: 1
        minimum: 1
    eventUIDFilterQueryParam:
      description: Filter by Event UID
      explode: true
      in: query
      name: eventUID
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
    filesQueryParam:
      example: _health.qo, data.qo
      in: query
      name: files
      required: false
      schema:
        type: string
    cursorParam:
      description: 'A cursor, which can be obtained from the `next_cursor` value from a previous call to this endpoint. The results set returned will include this event as its first result if the given identifier is actually the UID of an event. If this event UID is not found, the parameter is ignored and the results set is the same as if the parameter was not included.

        '
      in: query
      name: cursor
      required: false
      schema:
        type: string
    fleetUIDParam:
      in: path
      name: fleetUID
      required: true
      schema:
        type: string
    formatParam:
      description: Response format (JSON or CSV)
      in: query
      name: format
      required: false
      schema:
        type: string
        default: json
        enum:
        - json
        - csv
    deviceUIDParamQuery:
      description: A Device UID.
      explode: true
      in: query
      name: deviceUID
      required: false
      schema:
        type: array
        items:
          type: string
      style: form
    endDateParam:
      description: End date for filtering results, specified as a Unix timestamp
      example: 1657894210
      in: query
      name: endDate
      required: false
      schema:
        type: integer
        minimum: 0
    pageSizeParam:
      in: query
      name: pageSize
      required: false
      schema:
        type: integer
        default: 50
        maximum: 10000
        minimum: 1
    systemFilesOnlyParam:
      in: query
      name: systemFilesOnly
      required: false
      schema:
        type: boolean
    projectOrProductUIDParam:
      example: app:2606f411-dea6-44a0-9743-1130f57d77d8
      in: path
      name: projectOrProductUID
      required: true
      schema:
        type: string
    sortByParam:
      in: query
      name: sortBy
      required: false
      schema:
        type: string
        default: captured
        enum:
        - best_id
        - device_serial
        - device_uid
        - captured
        - modified
        - device_location
        - tower_location
        - triangulated_location
        - best_location
  responses:
    EventsByCursorResponse:
      description: The response body from a GET events by cursor request.
      content:
        application/json:
          schema:
            type: object
            properties:
              events:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
              has_more:
                description: True if there are more events
                type: boolean
              next_cursor:
                description: 'The cursor value of the next result, which is intended to be used as the "cursor" parameter value of the next call to this method. An empty string is returned if there are no more results after this results set.

                  '
                type: string
            required:
            - events
            - next_cursor
            - has_more
          example:
            events:
            - app: app:218f6217-9f78-432e-9fe0-02ca8b5a216c
              best_country: US
              best_id: My Device
              best_lat: 34.82476372
              best_location: Atlanta GA
              best_location_type: triangulated
              best_location_when: 1652709545
              best_lon: -83.32261614
              best_timezone: America/New_York
              body:
                humidity: 40.375
                pressure: 97705.66
                temperature: 24.0625
                voltage: 2.598
              device: dev:5c0272311928
              event: dfa3747d-688b-4250-935b-5dd60354313c
              file: air.qo
              product: product:com.blues.project.demo
              received: 1656011227.006928
              req: note.add
              session: b623132c-6afb-4740-bc39-e3634e38f064
              sn: My Device
              tower_id: 0,0,0,0
              tri_country: US
              tri_lat: 34.82475372
              tri_location: Atlanta GA
              tri_lon: -83.32261614
              tri_points: 6
              tri_timezone: America/New_York
              tri_when: 1652709545
              updates: 1
              when: 1656010061
            has_more: false
            next_cursor: ''
    EventsResponse:
      description: The response body from a GET events request.
      headers:
        X-Has-More:
          description: True if there are more events
          schema:
            type: boolean
      content:
        application/json:
          schema:
            type: object
            properties:
              events:
                type: array
                items:
                  $ref: '#/components/schemas/Event'
              has_more:
                description: True if there are more events
                type: boolean
              through:
                description: The UID of the last event returned
                type: string
            required:
            - events
            - has_more
          example:
            events:
            - app: app:218f6217-9f78-432e-9fe0-02ca8b5a216c
              best_country: US
              best_id: My Device
              best_lat: 34.82476372
              best_location: Atlanta GA
              best_location_type: triangulated
              best_location_when: 1652709545
              best_lon: -83.32261614
              best_timezone: America/New_York
              body:
                humidity: 40.375
                pressure: 97705.66
                temperature: 24.0625
                voltage: 2.598
              device: dev:5c0272311928
              event: dfa3747d-688b-4250-935b-5dd60354313c
              file: air.qo
              product: product:com.blues.project.demo
              received: 1656011227.006928
              req: note.add
              session: b623132c-6afb-4740-bc39-e3634e38f064
              sn: My Device
              tower_id: 0,0,0,0
              tri_country: US
              tri_lat: 34.82475372
              tri_location: Atlanta GA
              tri_lon: -83.32261614
              tri_points: 6
              tri_timezone: America/New_York
              tri_when: 1652709545
              updates: 1
              when: 1656010061
            has_more: true
        text/csv:
          schema:
            type: string
            properties: {}
            format: binary
          example: 'eventUID,deviceUID,when,best_location_type,best_lat,best_lon,body.temperature,body.humidity

            e123456-7890-abcd-ef01-234567890abc,dev:000000000000001,1625097600,gps,37.7749,-122.4194,22.5,45.2

            f234567-8901-bcde-fg12-345678901bcd,dev:000000000000002,1625097660,triangulated,40.7128,-74.0060,24.3,48.7

            g345678-9012-cdef-gh23-456789012cde,dev:000000000000003,1625097720,tower,51.5074,-0.1278,20.1,52.9

            '
    ErrorResponse:
      description: The response body in case of an API error.
      content:
        application/json:
          schema:
            type: ''
            properties: {}
            $ref: '#/components/schemas/Error'
  schemas:
    Error:
      type: object
      properties:
        code:
          description: The HTTP error code associated with the error.
          type: integer
          maximum: 599
          minimum: 300
        debug:
          type: string
        details:
          type: object
        err:
          description: Human readable error message.
          type: string
        request:
          type: string
        status:
          description: Machine readable representation of the HTTP error code.
          type: string
      required:
      - err
      - code
      - status
    Event:
      type: object
      properties:
        app:
          description: App UID (globally unique)
          type: string
        bars:
          description: Bars. Only available on _session.qo events.
          type: number
        best_country:
          description: Country
          type: string
        best_id:
          description: The device serial number, or the DeviceUID if the serial number is not set
          type: string
        best_lat:
          description: Latitude
          type: number
          format: double
        best_location:
          description: Location
          type: string
        best_location_type:
          description: One of "gps", "triangulated", or "tower"
          type: string
        best_location_when:
          description: Unix timestamp
          type: number
        best_lon:
          description: Longitude
          type: number
          format: double
        best_timezone:
          description: Timezone
          type: string
        body:
          description: A JSON object containing event details
          type: object
        bssid:
          description: BSSID. Only available on _session.qo events.
          type: string
        device:
          description: Device UID (globally unique)
          type: string
        environment:
          description: Routed environment variables beginning with "$". Only available on _session.qo events.
          type: object
        event:
          description: Event UID (globally unique)
          type: string
        file:
          description: The notefile associated with this event
          type: string
        moved:
          description: The number of times the device was sensed to have moved between the last session and this session. Only available on _session.qo events.
          type: number
        note:
          description: The note ID in the notefile
          type: string
        ordering_code:
          description: Ordering code. Only available on _session.qo events.
          type: string
        orientation:
          description: The orientation of the device. Only available on _session.qo events.
          type: string
        payload:
          description: A base64-encoded binary payload
          type: string
        product:
          description: Product UID (globally unique)
          type: string
        rat:
          description: Rat. Only available on _session.qo events.
          type: string
        received:
          description: The unix timestamp when the event was received
          type: number
          format: double
        req:
          description: The notecard request
          type: string
        rsrp:
          description: RSRP. Only available on _session.qo events.
          type: number
        rsrq:
          description: RSRQ. Only available on _session.qo events.
          type: number
        rssi:
          description: Received Signal Strength Indicator (RSSI) is an estimated measurement of how well a device can receive signals. Only available on _session.qo events.
          type: number
        session:
          description: Session UID (globally unique)
          type: string
        sinr:
          description: SINR. Only available on _session.qo events.
          type: number
        sku:
          description: SKU. Only available on _session.qo events.
          type: string
        sn:
          description: The device serial number
          type: string
        ssid:
          description: SSID. Only available on _session.qo events.
          type: string
        temp:
          description: Device temperature. Only available on _session.qo events.
          type: number
          format: double
        tls:
          description: Whether TLS was used on the connection between the device and notehub. Only available on _session.qo events.
          type: boolean
        tower_country:
          description: Country
          type: string
        tower_id:
          description: Tower ID
          type: string
        tower_lat:
          description: Latitude
          type: number
          format: double
        tower_location:
          description: Location
          type: string
        tower_lon:
          description: Longitude
          type: number
          format: double
        tower_timezone:
          description: Timezone
          type: string
        tower_when:
          description: Unix timestamp
          type: number
        transport:
          description: The transport used for this event, e.g., "cellular", "wifi", ", etc.
          type: string
        tri_country:
          description: Country
          type: string
        tri_lat:
          description: Latitude
          type: number
          format: double
        tri_location:
          description: Location
          type: string
        tri_lon:
          description: Longitude
          type: number
          format: double
        tri_points:
          description: Triangulation points
          type: number
        tri_timezone:
          description: Timezone
          type: string
        tri_when:
          description: Unix timestamp
          type: number
        updates:
          type: number
        voltage:
          description: Device voltage. Only available on _session.qo events.
          type: number
          format: double
        when:
          description: When the event was captured on the device
          type: number
        where_country:
          description: Country
          type: string
        where_lat:
          description: Latitude
          type: number
          format: double
        where_location:
          description: Location
          type: string
        where_lon:
          description: Longitude
          type: number
          format: double
        where_olc:
          description: Open Location Code
          type: string
        where_timezone:
          description: Timezone
          type: string
        where_when:
          description: Unix timestamp
          type: number
    RouteLog:
      type: object
      properties:
        attn:
          description: If true, an error was returned when routing
          type: boolean
        date:
          description: The date of the logs.
          type: string
        duration:
          description: The duration of the route in milliseconds
          type: integer
        event_uid:
          description: The event UID.
          type: string
        route_uid:
          description: The route UID.
          type: string
        status:
          description: The status of the event.
          type: string
        text:
          description: The response body of the route.
          type: string
        url:
          description: The URL of the route.
          type: string
  securitySchemes:
    personalAccessToken:
      description: 'Use a personal access token from notehub.io/api-access

        '
      scheme: bearer
      type: http
externalDocs:
  description: Find out more about Blues
  url: https://blues.io