Event API

The Notehub event API provides RESTful methods that can be used to GET event data.

Get Events by Project

Get an array of Notehub events by ProjectUID.

Minimum Notehub project-level role required:

note

This API reference displays all possible fields that can be present in an event response. However, certain fields will only be present for certain types of events (e.g. Note added event, Note updated event, .dbs update event, Notehub session event, etc).

Arguments

`access_token`

string

A Notehub API bearer token.

`projectUID`

string

The ProjectUID from a Notehub project.

`pageSize`

integer (optional)

Specifies the number of events to be returned by a request (default 50).

`pageNum`

integer (optional)

Specifies the page number of the results returned (useful when the pageSize is less than the total number of sessions that could be returned).

`deviceUID`

string (optional)

The DeviceUID of a Notehub device.

You may alternatively provide a device serial number by prefixing this argument with sn:, for example sn:my-device.

`sortBy`

string (optional)

Specifies a field in the result set to sort by, and must be one of the following: best_id, device_serial, device_uid, captured, modified, device_location, tower_location, triangulated_location, best_location.

`sortOrder`

string (optional)

Specifies the ascending (asc) or descending (desc) order of the result set when paired with sortBy. The default is asc.

`startDate`

UNIX Epoch time (optional)

The start date/time stamp of the events to be returned.

`endDate`

UNIX Epoch time (optional)

The end date/time stamp of the events to be returned.

`systemFilesOnly`

boolean (optional)

If true, will only return System Notefiles in the response.

`files`

string (optional)

A comma-delimited list of Notefile(s) this request should return events from. For example, setting this argument to track.qo,sensor.qo would return events only from the track.qo and sensor.qo Notefiles.

Response Members

`event`

string

The globally-unique EventUID.

`session`

string

The globally-unique SessionUID for the device's current Notehub session.

`best_id`

string

The device's best identifier. This is the device's serial number if set, or the device's DeviceUID if not.

`device`

string

The device's globally-unique DeviceUID.

`sn`

string

The device's serial number.

`product`

string

The globally-unique ProductUID.

`app`

string

The globally-unique AppUID for the device's current Notehub application.

`received`

UNIX Epoch time

The date and time this event was received by Notehub.

`req`

string

The API command used to create this event.

`when`

UNIX Epoch time

The date and time this event was captured by the device.

`file`

string

The name of the Notefile.

`updates`

number

The number of updates performed on a DB Notefile.

`body`

object

A JSON object containing the event details.

`best_location_type`

string

The type of location used as for all the "best" response fields, either "gps", "triangulated", or "tower".

`best_location_when`

UNIX Epoch time

The date and time the device last determined its location.

A device can have its location determined by GPS/GNSS, triangulation, or from the cell tower that received the event. The best_* fields provide the most accurate values from the available locations.

`best_lat`

number

The latitude of the device that sent the event.

`best_lon`

number

The longitude of the device that sent the event.

`best_location`

string

The name of the location from the device that sent the event.

`best_country`

string

The country of the device that sent the event.

`best_timezone`

string

The timezone of the location from the device that sent the event.

`tower_id`

string

A combination of the mcc, mnc, lac, and cid values, denoting the cell tower where the session originated.

`tower_country`

string

The country of the physical cell tower that received the event.

`tower_lat`

number

The latitude of the physical cell tower that received the event.

`tower_lon`

number

The longitude of the physical cell tower that received the event.

`tower_location`

string

The name of the location of the physical cell tower that received the event.

`tower_timezone`

string

The timezone used by the physical cell tower that received the event.

`tower_when`

UNIX Epoch time

The date and time the device retrieved the tower location.

`tri_when`

UNIX Epoch time

The date and time when the device retrieved its triangulated location.

`tri_lat`

number

The latitude of the device's triangulated location when it sent the event.

`tri_lon`

number

The longitude of the device's triangulated location when it sent the event.

`tri_location`

string

The name of the device's triangulated location when it sent the event.

`tri_country`

string

The country of the device's triangulated location when it sent the event.

`tri_timezone`

string

The timezone of the device's triangulated location when it sent the event.

`tri_points`

number

The number of Wi-Fi access points (if using Wi-Fi triangulation) or cell towers (if using cell-tower triangulation) used to determine the triangulated location.

`where_country`

string

The country from the device's GPS/GNSS location when it sent the event.

`where_lat`

number

The latitude from the device's GPS/GNSS location when it sent the event.

`where_lon`

number

The longitude from the device's GPS/GNSS location when it sent the event.

`where_location`

string

The name of the device's GPS/GNSS location when it sent the event.

`where_timezone`

string

The timezone from the device's GPS/GNSS location when it sent the event.

`where_when`

UNIX Epoch time

The date and time when the device last determined its GPS/GNSS location.

`through`

string

The globally-unique identifier of the last event in the array.

`has_more`

boolean

Defines whether or not there are additional events beyond this list.

Example Response


{
  "events": [
    {
      "event": "dfa3747d-688b-4250-935b-5dd60354313c",
      "session": "b623132c-6afb-4740-bc39-e3634e38f064",
      "best_id": "My Device",
      "device": "dev:5c0272311928",
      "sn": "My Device",
      "product": "product:com.blues.project.demo",
      "app": "app:3733f429-9335-6756-3456-c397c0000000",
      "received": 1656011227.006928,
      "req": "note.add",
      "when": 1656010061,
      "file": "203733583236500300070022#air.qo",
      "updates": 1,
      "body": {
        "humidity": 40.375,
        "pressure": 97705.66,
        "temperature": 24.0625,
        "voltage": 2.598
      },
      "best_location_type": "triangulated",
      "best_location_when": 1652709545,
      "best_lat": 34.82476372,
      "best_lon": -83.32261614,
      "best_location": "Atlanta GA",
      "best_country": "US",
      "best_timezone": "America/New_York",
      "tower_id": "0,0,0,0",
      "tri_when": 1652709545,
      "tri_lat": 34.82475372,
      "tri_lon": -83.32261614,
      "tri_location": "Atlanta GA",
      "tri_country": "US",
      "tri_timezone": "America/New_York",
      "tri_points": 6
    }
  ],
  "through": "dfa3747d-688b-4250-935b-5dd60354313c",
  "has_more": false
}

Get Events by Cursor

Get an array of Notehub events by ProjectUID and cursor (i.e. a means of limiting your result set).

Minimum Notehub project-level role required:

note

Arguments

`access_token`

string

A Notehub API bearer token.

`projectUID`

string

The ProjectUID from a Notehub project.

`deviceUID`

string (optional)

The DeviceUID of a Notehub device.

You may alternatively provide a device serial number by prefixing this argument with sn:, for example sn:my-device.

`limit`

integer (optional)

The number of records to return (minimum value is 1). Default value is 50.

`cursor`

string (optional)

The globally-unique EventUID obtained from the next_cursor value from a previous call to this API. The result set will include this event as its first result. However, if the provided EventUID is not valid, this parameter is ignored.

`sortOrder`

string (optional)

Specifies the ascending (asc) or descending (desc) order of the result set based on the timestamp at which the event was received in Notehub. The default is asc.

`systemFilesOnly`

boolean (optional)

If true, will only return System Notefiles in the response.

`files`

string (optional)

Limit the query to return only the Notefile(s) named in this argument (e.g. &files=track.qo,sensor.qo).


curl -X GET
     -L 'https://api.notefile.net/v1/projects/<projectUID>/events-cursor?limit=<limit>&cursor=<cursor>&sortOrder=<sortOrder>'
     -H 'Authorization: Bearer <access_token>'

Response Members

`events`

array

An array of events (see the Get Events by Project response for a full description of the data elements returned).

`next_cursor`

string

The cursor value of the next EventUID, which is intended to be used as the cursor parameter of the subsequent call to this API. An empty string is returned if there are no additional results to display.

`has_more`

boolean

Defines whether or not there are additional events beyond this list.

Example Response


{
  "events": [
    {
      "event": "dfa3747d-688b-4250-935b-5dd60354313c",
      "session": "b623132c-6afb-4740-bc39-e3634e38f064",
      "best_id": "My Device",
      "device": "dev:5c0272311928",
      "sn": "My Device",
      "product": "product:com.blues.project:demo",
      "app": "app:3733f429-9335-6756-3456-c397c0000000",
      "received": 1656011227.006928,
      "req": "note.add",
      "when": 1656010061,
      "file": "203733583236500300070022#air.qo",
      "updates": 1,
      "body": {
        "humidity": 40.375,
        "pressure": 97705.66,
        "temperature": 24.0625,
        "voltage": 2.598
      },
      "best_location_type": "triangulated",
      "best_location_when": 1652709545,
      "best_lat": 34.82476372,
      "best_lon": -83.32261614,
      "best_location": "Atlanta GA",
      "best_country": "US",
      "best_timezone": "America/New_York",
      "tower_id": "0,0,0,0",
      "tri_when": 1652709545,
      "tri_lat": 34.82475372,
      "tri_lon": -83.32261614,
      "tri_location": "Atlanta GA",
      "tri_country": "US",
      "tri_timezone": "America/New_York",
      "tri_points": 6
    }
  ],
  "next_cursor": "00000000-0000-0000-0000-000000000000",
  "has_more": false
}

Get Latest Events

Get the most recent health log, session, and note events by ProjectUID and DeviceUID (updated at the end of every session). If a device is in continuous mode, the latest events are updated every 15 minutes.

Minimum Notehub project-level role required:

note

Arguments

`access_token`

string

A Notehub API bearer token.

`projectUID`

string

The ProjectUID from a Notehub project.

`deviceUID`

string

The DeviceUID of a Notehub device.

You may alternatively provide a device serial number by prefixing this argument with sn:, for example sn:my-device.


curl -X GET
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/latest'
     -H 'Authorization: Bearer <access_token>'

Response Members

`latest_events`

array

An array of the latest events captured by the device (see the Get Events by Project response for a full description of the data elements returned).

Example Response


{
  "latest_events": [
    {
      "event": "916d4c81-06ae-4263-9b55-7a3a0f73cb5a",
      "session": "28cdc39f-9f62-4789-b0a3-2f35f9448ced",
      "device": "dev:864475040523995",
      "sn": "tj-1",
      "product": "product:com.blues.app:myapp",
      "app": "app:3733f429-9335-6756-3456-c397c0000000",
      "received": 1643991803.316966,
      "req": "note.add",
      "when": 1643991794,
      "file": "data.qo",
      "body": {
        "humid": 56.23,
        "temp": 35.5
      },
      "tower_when": 1643991727,
      "tower_lat": 43.769062500000004,
      "tower_lon": -83.657359375,
      "tower_country": "US",
      "tower_location": "Waverly MI",
      "tower_timezone": "America/Detroit",
      "tower_id": "310,410,20483,184692495"
    },
    {
      "event": "e98c2c3b-edbe-4fe7-af57-2196cc843eb7",
      "session": "7211392c-6895-43f8-9256-790655348be5",
      "device": "dev:864475040523995",
      "product": "product:com.blues.app:myapp",
      "received": 1663343137.75288,
      "req": "note.add",
      "when": 1663343125,
      "file": "sensors.qo",
      "body": {
        "humidity": 69.88647200683693,
        "pressure": 993.6294496104914,
        "temp": 21.273027181770885
      },
      "tower_when": 1663343102,
      "tower_lat": 43.747037500000005,
      "tower_lon": -83.665859375,
      "tower_country": "US",
      "tower_location": "Waverly MI",
      "tower_timezone": "America/Detroit",
      "tower_id": "310,410,20483,184692496"
    }
  ]
}

Get Health Log

Get an array of health log events by ProjectUID and DeviceUID.

Minimum Notehub project-level role required:

Arguments

`access_token`

string

A Notehub API bearer token.

`projectUID`

string

The ProjectUID from a Notehub project.

`deviceUID`

string

The DeviceUID of a Notehub device.

You may alternatively provide a device serial number by prefixing this argument with sn:, for example sn:my-device.


curl -X GET
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/health-log'
     -H 'Authorization: Bearer <access_token>'

Response Members

`when`

string

The date and time this event was received by Notehub.

`alert`

boolean

The date and time this event was received by Notehub.

`text`

string

Descriptive information about the health log event.

Example Response


{
  "health_log": [
    {
      "when": "2021-04-27T15:37:47Z",
      "alert": false,
      "text": "boot (brown-out \u0026 hard reset [12460])"
    }
  ]
}

Get Sessions

Get all session events by ProjectUID and DeviceUID.

Minimum Notehub project-level role required:

Arguments

`access_token`

string

A Notehub API bearer token.

`projectUID`

string

The ProjectUID from a Notehub project.

`deviceUID`

string

The DeviceUID of a Notehub device.

You may alternatively provide a device serial number by prefixing this argument with sn:, for example sn:my-device.

`pageSize`

integer (optional)

Specifies the number of sessions to be returned by a request (default 50).

`pageNum`

integer (optional)

Specifies the page number of the results returned (useful when the pageSize is less than the total number of sessions that could be returned).

Response Members

`session`

string

The globally-unique SessionUID for the device's current Notehub session.

`device`

string

The device's globally-unique DeviceUID.

`product`

string

The globally-unique ProductUID.

`fleets`

array

An array of device fleets to which this Notecard belongs.

`cell`

string

A combination of the mcc, mnc, lac, and cid values, denoting the cell tower where the session originated.

`rssi`

integer

The "Received Signal Strength Indicator" value (0 being the best possible signal strength).

`sinr`

integer

The "Signal to Interference and Noise Ratio" value (the higher the value the better the signal strength).

`rsrp`

integer

The "Reference Signal Received Power" value (the higher the value the stronger the power).

`rsrq`

integer

The "Reference Signal Received Quality" value (the higher the value the better the signal quality).

`bars`

integer

A general measure of the quality and strength of the cellular connection (with 4 being the highest quality).

`rat`

string

The "Radio Access Technology" (i.e. the underlying connection method for the cellular network).

`bearer`

string

The tunnel used to connect the device to Packet Data Networks (PDNs).

`ip`

string

The IP address of the Notehub.io handler.

`iccid`

string

The "Integrated Circuit Card Identifier" of the SIM on the device.

`apn`

string

The "Access Point Name" for Notehub.

`tower`

object

Information about the cell tower used for this Notehub session.

`tri`

object

Information about the triangulation method(s) used for this Notehub session (only if triangulation was utilized).

`when`

UNIX Epoch time

Last known capture time of a Note routed through this session.

`voltage`

decimal

The voltage of the attached power source.

`temp`

decimal

The temperature (in Celsius) as reported by the onboard temperature sensor.

`continuous`

boolean

Whether or not the Notecard is in the continuous connectivity mode.

`tls`

boolean

Whether or not TLS was used to secure this session.

`work`

UNIX Epoch time

The last time an update was made (e.g. a Notefile was added/updated) or other "work" was performed for this session.

`events`

integer

The number of events routed in this session.

`moved`

UNIX Epoch time

The last time motion was detected for this session.

`orientation`

string

The physical orientation of the Notecard.

`trigger`

string

The reason this session was initiated.

`hp_*`

integer

The hp_* values report "high power" statistics about when the modem was powered on. One cycle is one power on/off of the modem.

`period`

object

Information denoting the approximate data usage, TCP sessions, and Notes sent in this session.

`has_more`

boolean

Whether or not there are additional sessions to display.

Example Response


{
  "sessions": [
    {
      "session": "d76689be-37cd-423c-b695-7e0c19a2a264",
      "device": "dev:000000000000000",
      "product": "product:com.blues.demo:project",
      "fleets": ["fleet:46be9834-5te6-42c1-0000-b5ea05e248d7"],
      "cell": "310,410,17169,77315594",
      "rssi": -61,
      "sinr": 183,
      "rsrp": -91,
      "rsrq": -13,
      "bars": 2,
      "rat": "lte",
      "bearer": "LTE FDD",
      "ip": "10.68.56.193",
      "iccid": "89011704278500000000",
      "apn": "a-notehub.com.attz",
      "tower": {
        "time": 1667250835,
        "n": "Shorewood Hills WI",
        "c": "US",
        "lat": 43.0742625,
        "lon": -89.44239062499999,
        "zone": "America/Chicago",
        "mcc": 310,
        "mnc": 410,
        "lac": 17169,
        "cid": 77315594,
        "l": "86MG3HF5+P25",
        "count": 7,
        "towers": 1
      },
      "tri": {},
      "when": 1667251044,
      "voltage": 4.174,
      "temp": 24.437,
      "continuous": true,
      "tls": true,
      "work": 1667251046,
      "events": 14,
      "moved": 1667250807,
      "orientation": "face-up",
      "trigger": "first sync; continuous connection mode",
      "hp_secs_total": 7659,
      "hp_secs_data": 7659,
      "hp_cycles_total": 3,
      "hp_cycles_data": 3,
      "period": {
        "since": 1667250832,
        "duration": 215,
        "bytes_rcvd": 2501,
        "bytes_sent": 4138,
        "sessions_tls": 1,
        "notes_sent": 12
      }
    }
  ],
  "has_more": true
}

Get Events by Fleet

Get an array of Notehub events by FleetUID.

Minimum Notehub project-level role required:

note

Arguments

`access_token`

string

A Notehub API bearer token.

`projectUID`

string

The ProjectUID from a Notehub project.

`fleetUID`

string

The FleetUID from a device fleet.

`pageSize`

integer (optional)

Specifies the number of events to be returned by a request (default 50).

`pageNum`

integer (optional)

Specifies the page number of the results returned (useful when the pageSize is less than the total number of sessions that could be returned).

`deviceUID`

string (optional)

Filter events by a single DeviceUID.

`sortBy`

string (optional)

`sortOrder`

string (optional)

Specifies the ascending (asc) or descending (desc) order of the result set when paired with sortBy. The default is asc.

`startDate`

UNIX Epoch time (optional)

The start date/time stamp of the events to be returned.

`endDate`

UNIX Epoch time (optional)

The end date/time stamp of the events to be returned.

`systemFilesOnly`

boolean (optional)

If true, will only return System Notefiles in the response.

`files`

string (optional)

Limit the query to return only the Notefile(s) named in this argument (e.g. &files=track.qo,sensor.qo).

Response Members

`events`

array

An array of events (see the Get Events by Project response for a full description of the data elements returned).

`through`

string

The globally-unique identifier of the last event in the array.

`has_more`

boolean

Defines whether or not there are additional events beyond this list.

Example Response


{
  "events": [
    {
      "event": "dfa3747d-688b-4250-935b-5dd60354313c",
      "session": "b623132c-6afb-4740-bc39-e3634e38f064",
      "best_id": "My Device",
      "device": "dev:5c0272311928",
      "sn": "My Device",
      "product": "product:com.blues.project.demo",
      "app": "app:3733f429-9335-6756-3456-c397c0000000",
      "received": 1656011227.006928,
      "req": "note.add",
      "when": 1656010061,
      "file": "203733583236500300070022#air.qo",
      "updates": 1,
      "body": {
        "humidity": 40.375,
        "pressure": 97705.66,
        "temperature": 24.0625,
        "voltage": 2.598
      },
      "best_location_type": "triangulated",
      "best_location_when": 1652709545,
      "best_lat": 34.82476372,
      "best_lon": -83.32261614,
      "best_location": "Atlanta GA",
      "best_country": "US",
      "best_timezone": "America/New_York",
      "tower_id": "0,0,0,0",
      "tri_when": 1652709545,
      "tri_lat": 34.82475372,
      "tri_lon": -83.32261614,
      "tri_location": "Atlanta GA",
      "tri_country": "US",
      "tri_timezone": "America/New_York",
      "tri_points": 6
    }
  ],
  "through": "dfa3747d-688b-4250-935b-5dd60354313c",
  "has_more": false
}

Get Fleet Events by Cursor

Get an array of Notehub events by FleetUID and cursor (i.e. a means of limiting your result set).

Minimum Notehub project-level role required:

note

Arguments

`access_token`

string

A Notehub API bearer token.

`projectUID`

string

The ProjectUID from a Notehub project.

`fleetUID`

string

The FleetUID from a device fleet.

`limit`

integer (optional)

The number of records to return (minimum value is 1). Default value is 50.

`cursor`

string (optional)

`sortOrder`

string (optional)

Specifies the ascending (asc) or descending (desc) order of the result set based on the timestamp at which the event was received in Notehub. The default is asc.

`systemFilesOnly`

boolean (optional)

If true, will only return System Notefiles in the response.

`files`

string (optional)

Limit the query to return only the Notefile(s) named in this argument (e.g. &files=track.qo,sensor.qo).


curl -X GET
     -L 'https://api.notefile.net/v1/projects/<projectUID>/fleets/<fleetUID>/events-cursor?limit=<limit>&cursor=<cursor>&sortOrder=<sortOrder>'
     -H 'Authorization: Bearer <access_token>'

Response Members

`events`

array

An array of events (see the Get Events by Project response for a full description of the data elements returned).

`next_cursor`

string

The globally-unique identifier of the last event in the array.

`has_more`

boolean

Defines whether or not there are additional events beyond this list.

Example Response


{
  "events": [
    {
      "event": "dfa3747d-688b-4250-935b-5dd60354313c",
      "session": "b623132c-6afb-4740-bc39-e3634e38f064",
      "best_id": "My Device",
      "device": "dev:5c0272311928",
      "sn": "My Device",
      "product": "product:com.blues.project.demo",
      "app": "app:3733f429-9335-6756-3456-c397c0000000",
      "received": 1656011227.006928,
      "req": "note.add",
      "when": 1656010061,
      "file": "203733583236500300070022#air.qo",
      "updates": 1,
      "body": {
        "humidity": 40.375,
        "pressure": 97705.66,
        "temperature": 24.0625,
        "voltage": 2.598
      },
      "best_location_type": "triangulated",
      "best_location_when": 1652709545,
      "best_lat": 34.82476372,
      "best_lon": -83.32261614,
      "best_location": "Atlanta GA",
      "best_country": "US",
      "best_timezone": "America/New_York",
      "tower_id": "0,0,0,0",
      "tri_when": 1652709545,
      "tri_lat": 34.82475372,
      "tri_lon": -83.32261614,
      "tri_location": "Atlanta GA",
      "tri_country": "US",
      "tri_timezone": "America/New_York",
      "tri_points": 6
    }
  ],
  "next_cursor": "00000000-0000-0000-0000-000000000000",
  "has_more": false
}

Environment Variable API File API