Notecard API Reference

Generated from notecard-schema version 0.1.1 (API Version: 9.1.1)

API Reference

The Notecard accepts requests in JSON format. Each request object must contain a req or cmd field specifying the request type. E.g. {"req": "card.status"} or {"cmd": "card.status"}

Warning

If you are looking for the Notecard API Reference, please visit blues.dev. This site intended for LLM agents and may lack complete documentation.

`card.attn`

Request

Configure hardware notification from the Notecard to MCU host. Note: Requires a connection between the Notecard ATTN pin and a GPIO pin on the host MCU.

Parameters:

Parameter	Type	Description	Default
`files`	`array`	An array of Notefile names to monitor for changes	`-`
`mode`	`string`	Configures the interaction model of the ATTN pin. Allowed values (comma separated): `-all`, `-env`, `-files`, `-location`, `-motion`, `-usb`, `arm`, `auxgpio`, `connected`, `disarm`, `env`, `files`, `location`, `motion`, `motionchange`, `rearm`, `signal`, `sleep`, `usb`, `watchdog`, `wireless`	`-`
`off`	`boolean`	Disables event monitoring, and sets ATTN pin to LOW	`-`
`on`	`boolean`	Enables event monitoring, and sets ATTN pin to HIGH	`-`
`payload`	`string`	The payload to send to the Notecard during 'sleep' mode	`-`
`seconds`	`integer`	Duration in seconds for the corresponding 'mode' value	`-`
`start`	`boolean`	Request to return stored `payload` after 'sleep' mode	`-`
`verify`	`boolean`	Returns the current event monitor configuration	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`set`	`boolean`	State of the ATTN pin	`-`
`files`	`array`	An array of Notefile events triggering the ATTN pin	`-`
`payload`	`string`	Echoes the payload to provided to the Notecard during 'sleep' mode	`-`
`time`	`integer`	Unix epoch timestamp of the 'payload' value	`-`
`off`	`boolean`	Present when event monitoring is disabled	`-`

`card.aux`

Request

Configure various uses of the general-purpose I/O (GPIO) pins AUX1-AUX4 on the Notecard edge connector for tracking applications and simple GPIO sensing and counting tasks.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	The AUX mode. Allowed values: `dfu`, `gpio`, `led`, `monitor`, `motion`, `neo`, `neo-monitor`, `off`, `track`, `track-monitor`, `track-neo-monitor`, `-`	`-`
`usage`	`array`	An ordered list of pin modes for each AUX pin when in GPIO mode	`-`
`seconds`	`integer`	When in gpio mode, if an AUX pin is configured as a count type, the count of rising edges can be broken into samples of this duration	`-`
`max`	`integer`	When in gpio mode, if an AUX pin is configured as a count type, the maximum number of samples of duration seconds	`-`
`start`	`boolean`	When in gpio mode, if an AUX pin is configured as a count type, set to true to reset counters and start incrementing	`-`
`gps`	`boolean`	Deprecated. If true, along with mode:track the Notecard supports the use of an external GPS module	`-`
`rate`	`integer`	The AUX UART baud rate for debug communication over the AUXRX and AUXTX pins. Allowed values: `300`, `600`, `1200`, `2400`, `4800`, `9600`, `19200`, `38400`, `57600`, `115200`, `230400`, `460800`, `921600`	`115200`
`sync`	`boolean`	If true, for pins set as input by usage, the Notecard will autonomously report any state changes as new notes in file	`-`
`file`	`string`	The name of the Notefile used to report state changes when used in conjunction with sync:true	`-`
`connected`	`boolean`	If true, defers the sync of the state change Notefile to the next sync as configured by the hub.set request	`-`
`limit`	`boolean`	If true, along with mode:track and gps:true the Notecard will disable concurrent modem use during GPS tracking	`-`
`sensitivity`	`integer`	When used with mode:neo-monitor or mode:track-neo-monitor, this controls the brightness of NeoPixel lights	`-`
`ms`	`integer`	When in gpio mode, this argument configures a debouncing interval	`-`
`count`	`integer`	When used with mode:neo-monitor or mode:track-neo-monitor, this controls the number of NeoPixels to use in a strip. Allowed values: `1`, `2`, `5`	`-`
`offset`	`integer`	When used with mode:neo-monitor or mode:track-neo-monitor, this is the 1-based index in a strip of NeoPixels	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	The current mode of the AUX interface	`-`
`text`	`string`	Text received over the AUX interface	`-`
`binary`	`string`	Binary data received over the AUX interface	`-`
`count`	`integer`	Number of bytes received	`-`

`card.aux.serial`

Request

Configure various uses of the AUXTX and AUXRX pins on the Notecard's edge connector.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	The AUX mode. Must be one of the following. Allowed values: `req`, `gps`, `notify`, `notify,accel`, `notify,signals`, `notify,env`, `notify,dfu`	`-`

Response

No description available.

No specific parameters defined.

`card.binary`

Request

View the status of the binary storage area of the Notecard and optionally clear any data and related card.binary variables.

Parameters:

Parameter	Type	Description	Default
`delete`	`boolean`	Clear the COBS area on the Notecard and reset all related arguments previously set by a card.binary request	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`cobs`	`integer`	The size of COBS-encoded data stored in the reserved area	`-`
`connected`	`boolean`	Returns true if the Notecard is connected to the network	`-`
`err`	`string`	If present, a string describing the error that occurred during transmission	`-`
`length`	`integer`	The length of the binary data	`-`

`card.binary.get`

Request

Returns binary data stored in the binary storage area of the Notecard. The response to this API command first returns the JSON-formatted response object, then the binary data.

Parameters:

Parameter	Type	Description	Default
`cobs`	`integer`	The size of the COBS-encoded data you are expecting to be returned (in bytes)	`-`
`offset`	`integer`	Used along with length, the number of bytes to offset the binary payload from 0 when retrieving binary data from the Notecard	`-`
`length`	`integer`	Used along with offset, the number of bytes to retrieve from the binary storage area of the Notecard	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`status`	`string`	The MD5 checksum of the data returned, after it has been decoded	`-`
`err`	`string`	If present, a string describing the error that occurred during transmission	`-`

`card.binary.put`

Request

Adds binary data to the binary storage area of the Notecard. The Notecard expects to receive binary data immediately following the usage of this API command.

Parameters:

Parameter	Type	Description	Default
`offset`	`integer`	The number of bytes to offset the binary payload from 0 when appending the binary data to the binary storage area of the Notecard	`-`
`cobs`	`integer`	The size of the COBS-encoded data (in bytes)	`-`
`status`	`string`	The MD5 checksum of the data, before it has been encoded	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`err`	`string`	If present, a string describing the error that occurred during transmission	`-`

`card.carrier`

Request

Uses the AUX_CHARGING pin on the Notecard edge connector to notify the Notecard that the pin is connected to a Notecarrier that supports charging, using open-drain.

Once set, {"charging":true} will appear in a response if the Notecarrier is currently indicating that charging is in progress.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	The `AUX_CHARGING` mode. Set to `"charging"` to tell the Notecard that `AUX_CHARGING` is connected to a Notecarrier that supports charging on `AUX_CHARGING`. Set to `"-"` or `"off"` to turn off the `AUX_CHARGING` detection.. Allowed values: `charging`, `-`, `off`	`-`

Examples:

Set the AUX_CHARGING mode to charging

{
  "req": "card.carrier",
  "mode": "charging"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	The current AUX_CHARGING mode, or `off` if not set	`-`
`charging`	`boolean`	Will display `true` when in AUX_CHARGING `charging` mode	`-`

Examples:

Get the AUX_CHARGING mode

{
  "mode": "charging",
  "charging": true
}

`card.contact`

Request

Used to set or retrieve information about the Notecard maintainer. Once set, this information is synched to Notehub.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Set the name of the Notecard maintainer	`-`
`org`	`string`	Set the organization name of the Notecard maintainer	`-`
`role`	`string`	Set the role of the Notecard maintainer	`-`
`email`	`string`	Set the email address of the Notecard maintainer	`-`

Examples:

Set Contact Information

{
  "req": "card.contact",
  "name": "Tom Turkey",
  "org": "Blues",
  "role": "Head of Security",
  "email": "tom@blues.com"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the Notecard maintainer	`-`
`org`	`string`	Organization name of the Notecard maintainer	`-`
`role`	`string`	Role of the Notecard maintainer	`-`
`email`	`string`	Email address of the Notecard maintainer	`-`

Examples:

Get Contact Information

{
  "name": "Tom Turkey",
  "org": "Blues",
  "role": "Head of Security",
  "email": "tom@blues.com"
}

`card.dfu`

Request

Used to configure a Notecard for Notecard Outboard Firmware Update.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	One of the supported classes of host MCU. Supported MCU classes are 'esp32', 'stm32', 'stm32-bi', '-'. Allowed values: `esp32`, `stm32`, `stm32-bi`, `-`	`-`
`on`	`boolean`	Set to true to enable Notecard Outboard Firmware Update	`-`
`off`	`boolean`	Set to true to disable Notecard Outboard Firmware Update from occurring	`-`
`seconds`	`integer`	When used with 'off':true, disable Notecard Outboard Firmware Update operations for the specified number of seconds	`-`
`stop`	`boolean`	Set to true to disable the host RESET that is normally performed on the host MCU when the Notecard starts up	`-`

Response

No description available.

No specific parameters defined.

`card.illumination`

SKUs

CELL CELL+WIFI WIFI

Request

This request returns an illumination reading (in lux) from an OPT3001 ambient light sensor connected to Notecard's I2C bus. If no OPT3001 sensor is detected, this request returns an “illumination sensor is not available” error.

Examples:

Example

{
  "req": "card.illumination"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`value`	`number`	An illumination reading (in lux) from the attached OPT3001 sensor.	`-`

Examples:

Example Response

{
  "value": 8806.4
}

`card.io`

Request

Can be used to override the Notecard's I2C address from its default of 0x17 and change behaviors of the onboard LED and USB port.

Parameters:

Parameter	Type	Description	Default
`i2c`	`integer`	The alternate address to use for I2C communication. Pass `-1` to reset to the default address	`-`
`mode`	`string`	- Allowed Values: - `-usb`: Set to `"-usb"` to disable the Notecard's USB port. Re-enable the USB port with `"usb"` or `"+usb"`. - `+busy`: If set to `"+busy"`, the Notecard's LED will be on when the Notecard is awake, and off when the Notecard goes to sleep. - `-busy`: Resets `"+busy"` to its default, making the onboard LED blink only during Notecard flash memory operations. - `i2c-master-disable`: Disables Notecard acting as an I2C master. Re-enable by using `"i2c-master-enable"`.	`-`

Examples:

Change I2C Address

{
  "req": "card.io",
  "i2c": 24
}

Keep LED On While Notecard Awake.

{
  "req": "card.io",
  "mode": "+busy"
}

Disable Notecard Acting As I2C Master.

{
  "req": "card.io",
  "mode": "i2c-master-disable"
}

Response

No description available.

No specific parameters defined.

`card.led`

Request

Used along with the card.aux API to turn connected LEDs on/off (not supported by Notecard LoRa), or to manage a single connected NeoPixel.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	Used to specify the color of the LED to turn on or off. Possible values for LEDs are 'red', 'green', 'yellow'. For NeoPixels, possible values are 'red', 'green', 'blue', 'yellow', 'cyan', 'magenta', 'orange', 'white', 'gray'. Allowed values: `red`, `green`, `yellow`, `blue`, `cyan`, `magenta`, `orange`, `white`, `gray`	`-`
`on`	`boolean`	Set to true to turn the specified LED or NeoPixel on	`-`
`off`	`boolean`	Set to true to turn the specified LED or NeoPixel off	`-`

Response

No description available.

No specific parameters defined.

`card.location`

Request

Retrieves the last known location of the Notecard and the time at which it was acquired. Use card.location.mode to configure location settings.

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`status`	`string`	The current status of the Notecard GPS/GNSS connection	`-`
`mode`	`string`	The GPS/GNSS connection mode. Will be continuous, periodic, or off. Allowed values: `continuous`, `periodic`, `off`	`-`
`lat`	`number`	The latitude in degrees of the last known location	`-`
`lon`	`number`	The longitude in degrees of the last known location	`-`
`time`	`integer`	Unix epoch time in seconds	`-`
`max`	`integer`	Maximum number of seconds to wait for a GPS fix	`-`

`card.location.mode`

Request

Sets location-related configuration settings. Retrieves the current location mode when passed with no argument.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	Must be one of: empty string to retrieve the current mode, 'off' to turn location mode off, 'periodic' to sample location at a specified interval, 'continuous' to enable the Notecard's GPS/GNSS module for continuous sampling, or 'fixed' to report the location as a fixed location. Allowed values: `,off`,`periodic`,`continuous`,`fixed`	`-`
`seconds`	`integer`	When in periodic mode, location will be sampled at this interval, if the Notecard detects motion	`-`
`vseconds`	`string`	In periodic mode, overrides seconds with a voltage-variable value	`-`
`lat`	`number`	Used with fixed mode to specify the latitude coordinate	`-`
`lon`	`number`	Used with fixed mode to specify the longitude coordinate	`-`
`max`	`integer`	Maximum number of seconds to wait for a GPS fix	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	The GPS/GNSS connection mode. Will be continuous, periodic, or off. Allowed values: `continuous`, `periodic`, `off`, `fixed`	`-`
`seconds`	`integer`	When in periodic mode, location will be sampled at this interval, if the Notecard detects motion	`-`
`lat`	`number`	The latitude in degrees of the last known location	`-`
`lon`	`number`	The longitude in degrees of the last known location	`-`
`max`	`integer`	Maximum number of seconds to wait for a GPS fix	`-`

`card.location.track`

Request

Store location data in a Notefile at the periodic interval, or using a specified heartbeat.

Parameters:

Parameter	Type	Description	Default
`start`	`boolean`	Set to true to start Notefile tracking	`-`
`heartbeat`	`boolean`	When start is true, set to true to enable tracking even when motion is not detected	`-`
`hours`	`integer`	If heartbeat is true, add a heartbeat entry at this hourly interval. Use a negative integer to specify a heartbeat in minutes instead of hours	`-`
`sync`	`boolean`	Set to true to perform an immediate sync to the Notehub each time a new Note is added	`-`
`stop`	`boolean`	Set to true to stop Notefile tracking	`-`
`file`	`string`	The name of the Notefile to store location data in	`track.qo`

Response

No description available.

No specific parameters defined.

`card.monitor`

SKUs

CELL CELL+WIFI WIFI

Request

When a Notecard is in monitor mode, this API is used to configure the general-purpose AUX1-AUX4 pins to test and monitor Notecard activity.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	Can be set to one of `green`, `red` or `yellow` to temporarily override the behavior of an AUX pin LED.

Examples:

Example

{
  "req": "card.monitor",
  "mode": "green",
  "count": 5
}

Response

No description available.

No specific parameters defined.

`card.motion`

Request

Returns information about the Notecard accelerometer's motion and orientation. Motion tracking must be enabled first with card.motion.mode. Otherwise, this request will return {}.

Parameters:

Parameter	Type	Description	Default
`minutes`	`integer`	Amount of time to sample for buckets of accelerometer-measured movement	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`count`	`integer`	The number of accelerometer motion events since the last card.motion request was made	`-`
`status`	`string`	The current status of the Notecard accelerometer	`-`
`alert`	`boolean`	If true, the Notecard's accelerometer detected a free-fall since the last request to card.motion	`-`
`motion`	`integer`	Time of the last accelerometer motion event	`-`
`seconds`	`integer`	Number of seconds since the last motion event	`-`
`movements`	`string`	String with motion counts in each bucket	`-`

`card.motion.mode`

Request

Configures accelerometer motion monitoring parameters used when providing results to card.motion.

Parameters:

Parameter	Type	Description	Default
`start`	`boolean`	Set to true to enable the Notecard accelerometer and start motion tracking	`-`
`stop`	`boolean`	Set to true to disable the Notecard accelerometer and stop motion tracking	`-`
`seconds`	`integer`	Period for each bucket of movements to be accumulated when minutes is used with card.motion	`-`
`sensitivity`	`integer`	Used to set the accelerometer sample rate	`-`

Response

No description available.

No specific parameters defined.

`card.motion.sync`

Request

Configures automatic sync triggered by Notecard movement.

Parameters:

Parameter	Type	Description	Default
`start`	`boolean`	Set to true to start motion-triggered syncing	`-`
`stop`	`boolean`	Set to true to stop motion-triggered syncing	`-`
`minutes`	`integer`	The maximum frequency at which sync will be triggered	`-`
`count`	`integer`	The number of most recent motion buckets to examine	`-`
`threshold`	`integer`	The number of buckets that must indicate motion in order to trigger a sync	`-`

Response

No description available.

No specific parameters defined.

`card.motion.track`

Request

Configures automatic capture of Notecard accelerometer motion in a Notefile.

Parameters:

Parameter	Type	Description	Default
`start`	`boolean`	Set to true to start motion capture	`-`
`stop`	`boolean`	Set to true to stop motion capture	`-`
`minutes`	`integer`	The maximum period to capture Notes in the Notefile	`-`
`count`	`integer`	The number of most recent motion buckets to examine	`-`
`threshold`	`integer`	The number of buckets that must indicate motion in order to capture	`-`
`file`	`string`	The Notefile to use for motion capture Notes	`_motion.qo`
`now`	`boolean`	Set to true to trigger the immediate creation of a motion.qo event if the orientation of the Notecard changes	`-`

Response

No description available.

No specific parameters defined.

`card.power`

SKUs

CELL CELL+WIFI WIFI

Request

The card.power API is used to configure a connected Mojo device or to manually request power consumption readings in firmware.

Parameters:

Parameter	Type	Description	Default
`minutes`	`integer`	How often, in minutes, Notecard should log power consumption in a `_log.qo` Note. The default value is `720` (12 hours).	`720`
`reset`	`boolean`	Set to `true` to reset the power consumption counters back to 0.	`-`

Examples:

Get Latest Power Consumption Reading

{
  "req": "card.power"
}

Set Cadence of Readings

{
  "req": "card.power",
  "minutes": 60
}

Reset Counters

{
  "cmd": "card.power",
  "reset": true
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`temperature`	`number`	The temperature from Notecard's onboard sensor in degrees centigrade, including the calibration offset.	`-`
`voltage`	`number`	The current voltage.	`-`
`milliamp_hours`	`number`	The cumulative number of milliamp hours (mAh) consumed. You can reset this number with this request's `reset` argument.	`-`

Examples:

Example Response

{
  "temperature": 26.028314208984398,
  "voltage": 4.200970458984375,
  "milliamp_hours": 3.9566722000000007
}

`card.random`

SKUs

CELL CELL+WIFI WIFI

Request

Obtain a single random 32 bit unsigned integer modulo count or count bytes of random data from the Notecard hardware random number generator.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	Accepts a single value `"payload"` and, if specified, uses the `count` value to determine the number of bytes of random data to generate and return to the host.	`-`
`count`	`integer`	If the mode argument is excluded from the request, the Notecard uses this as an upper-limit parameter and returns a random unsigned 32 bit integer between zero and the value provided.

If "mode":"payload" is used, this argument sets the number of random bytes of data to return in a base64-encoded buffer from the Notecard. | - |

Examples:

Get a Random Number.

{
  "req": "card.random",
  "count": 100
}

Get a Buffer of Random Numbers

{
  "req": "card.random",
  "mode": "payload",
  "count": 100
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`count`	`integer`	A random number generated by the Notecard's onboard hardware random number generator.	`-`
`payload`	`string`	If using `"mode":"payload"`, a base64-encoded string with random values, the length of which is specified by the `count` argument.	`-`

Examples:

Example Response

{
  "count": 86
}

`card.restart`

Request

Performs a firmware restart of the Notecard.

Response

No description available.

No specific parameters defined.

`card.restore`

Request

Performs a factory reset on the Notecard and restarts.

Sending this request without either of the optional arguments below will only reset the Notecard's file system, thus forcing a re-sync of all Notefiles from Notehub.

On Notecard LoRa there is no option to retain configuration settings, and providing "delete": true is required. The Notecard LoRa retains LoRaWAN configuration after factory resets.

Parameters:

Parameter	Type	Description	Default
`connected`	`boolean`	Set to true to reset the Notecard on Notehub. This will delete and deprovision the Notecard from Notehub the next time the Notecard connects. This also removes any Notefile templates used by this device.

Conversely, if connected is false (or omitted), the Notecard's settings and data will be restored from Notehub the next time the Notecard connects to the previously used Notehub project. | - | | delete | boolean | Set to true to reset most Notecard configuration settings. Note that this does not reset stored Wi-Fi credentials or the alternate I2C address (if previously set) so the Notecard can still contact the network after a reset.

The Notecard will be unable to sync with Notehub until the ProductUID is set again. | - |

Response

No description available.

No specific parameters defined.

`card.status`

Request

Returns general information about the Notecard's operating status.

Examples:

Get Notecard Status

{
  "req": "card.status"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`status`	`string`	General status information	`-`
`usb`	`boolean`	`true`, if the Notecard is being powered by USB	`-`
`storage`	`integer`	The percentage of storage in use on the Notecard	`-`
`time`	`integer`	The UNIX Epoch Time of approximately when the Notecard was first powered up	`-`
`connected`	`boolean`	`true`, if the Notecard is connected to the Notehub	`-`
`cell`	`boolean`	`true`, if the Notecard has a cellular connection	`-`
`gps`	`boolean`	`true`, if Notecard's GPS module is currently powered on	`-`
`wifi`	`boolean`	`true`, if the Notecard's Wi-Fi radio is currently powered on	`-`
`sync`	`boolean`	`true`, if the Notecard is currently syncing with the Notehub	`-`
`inbound`	`integer`	The effective inbound synchronization period being used by the device	`-`
`outbound`	`integer`	The effective outbound synchronization period being used by the device	`-`

Examples:

Get Notecard Status Response

{
  "status": "{normal}",
  "usb": true,
  "storage": 8,
  "time": 1599684765,
  "connected": true,
  "cell": true,
  "sync": true,
  "inbound": 60,
  "outbound": 360
}

`card.temp`

Request

Get the current temperature from the Notecard's onboard calibrated temperature sensor.

Parameters:

Parameter	Type	Description	Default
`minutes`	`integer`	If specified, creates a templated _temp.qo file that gathers Notecard temperature value at the specified minutes interval	`-`
`status`	`string`	Overrides minutes with a voltage-variable value	`-`
`stop`	`boolean`	If set to true, the Notecard will stop logging the temperature value at the interval specified with the minutes parameter	`-`
`sync`	`boolean`	If set to true, the Notecard will immediately sync any pending _temp.qo Notes created with the minutes parameter	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`temperature`	`number`	Temperature in degrees C	`-`
`humidity`	`number`	Relative humidity percentage (when using BME280 or ENS210 sensor)	`-`
`pressure`	`number`	Barometric pressure in hPa (when using BME280 or ENS210 sensor)	`-`

`card.time`

Request

Retrieves current date and time information in UTC (UNIX timestamp). Upon power-up, the Notecard must complete a sync to Notehub in order to obtain time and location data. Before the time is obtained, this request will return {"zone":"UTC,Unknown"}.

Examples:

Gets current date and time information in UTC (UNIX timestamp).

{
  "req": "card.time"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`time`	`integer`	The current time in UTC (UNIX timestamp). Will only populate if the Notecard has completed a sync to Notehub to obtain the time.	`-`
`area`	`string`	The geographic area of the Notecard, if the cell tower is recognized	`-`
`zone`	`string`	The time zone of the Notecard, if the cell tower is recognized.	`-`
`minutes`	`integer`	Number of minutes East of GMT, if the cell tower is recognized.	`-`
`lat`	`number`	Latitude of the Notecard, if the cell tower is recognized.	`-`
`lon`	`number`	Longitude of the Notecard, if the cell tower is recognized.	`-`
`country`	`string`	The country where the Notecard is located, if the cell tower is recognized.	`-`

Examples:

Returns the current date and time information in UTC (UNIX timestamp).

{
  "time": 1599769214,
  "area": "Beverly, MA",
  "zone": "CDT,America/New York",
  "minutes": -300,
  "lat": 42.5776,
  "lon": -70.87134,
  "country": "US"
}

`card.transport`

SKUs

CELL CELL+WIFI WIFI

Request

Specifies the connectivity protocol to prioritize on the Notecard Cell+WiFi, or when using NTN mode with Starnote and a compatible Notecard.

Parameters:

Parameter	Type	Description	Default
`method`	`string`	The connectivity method to enable on the Notecard. Allowed Values: - `-`: Resets the transport mode to the device default. (`CELL`, `CELL+WIFI`, `WIFI`) - `cell`: Enables cellular only on the device. (`CELL`, `CELL+WIFI`) - `cell-ntn`: Prioritizes cellular connectivity while falling back to NTN if a cellular connection cannot be established. (`CELL`, `CELL+WIFI`) - `dual-wifi-cell`: Deprecated form of `"wifi-cell"` (`CELL+WIFI`) - `ntn`: Enables NTN (Non-Terrestrial Network) mode on the device for use with Starnote. (`CELL`, `CELL+WIFI`, `WIFI`) - `wifi`: Enables Wi-Fi only on the device. (`CELL+WIFI`, `WIFI`) - `wifi-cell`: Prioritizes Wi-Fi connectivity while falling back to cellular if a Wi-Fi connection cannot be established. This is the default behavior on Notecard Cell+WiFi. (`CELL+WIFI`) - `wifi-cell-ntn`: Prioritizes Wi-Fi connectivity while falling back to cellular, and lastly to NTN. (`CELL+WIFI`) - `wifi-ntn`: Prioritizes Wi-Fi connectivity while falling back to NTN if a Wi-Fi connection cannot be established. (`CELL+WIFI`, `WIFI`)	`-`
`seconds`	`integer`	The amount of time a Notecard will spend on any fallback transport before retrying the first transport specified in the `method`. The default is `3600` or 60 minutes.	`3600`
`allow`	`boolean`	Set to `true` to allow adding Notes to non-compact Notefiles while connected over a non-terrestrial network.

Examples:

Example

{
  "req": "card.transport",
  "method": "wifi-cell"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`method`	`string`	The connectivity method currently enabled on the device.	`-`

Examples:

Response for card.transport with method set to wifi-cell.

{
  "method": "wifi-cell"
}

`card.usage.get`

Request

Returns the card's network usage statistics.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	The time period to use for statistics. Allowed Values: - `total`: All stats since the Notecard was activated.	`total`
`offset`	`integer`	The number of time periods to look backwards, based on the specified `mode`.

To accurately determine the start of the calculated time period when using offset, use the time value of the response. Likewise, to calculate the end of the time period, add the seconds value to the time value. | - |

Examples:

Example

{
  "req": "card.usage.get",
  "mode": "1day",
  "offset": 5
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`seconds`	`integer`	Number of seconds in the analyzed period.	`-`
`time`	`integer`	Start time (Unix epoch seconds) of the analyzed period or, if `mode="total"`, the time of activation.	`-`
`bytes_sent`	`integer`	Number of bytes sent by the Notecard to Notehub.	`-`
`bytes_received`	`integer`	Number of bytes received by the Notecard from Notehub.	`-`
`notes_sent`	`integer`	Approximate number of Notes sent by the Notecard to Notehub.	`-`
`notes_received`	`integer`	Approximate number of Notes received by the Notecard from Notehub.	`-`
`sessions_standard`	`integer`	Number of standard Notehub sessions.	`-`
`sessions_secure`	`integer`	Number of secure Notehub sessions.	`-`

Examples:

Example Response

{
  "seconds": 1291377,
  "time": 1598479763,
  "bytes_sent": 163577,
  "bytes_received": 454565,
  "notes_sent": 114,
  "notes_received": 26,
  "sessions_standard": 143,
  "sessions_secure": 31
}

`card.usage.test`

SKUs

CELL CELL+WIFI WIFI

Request

Request schema for card.usage.test API command.

Parameters:

Parameter	Type	Description	Default
`days`	`integer`	Number of days to use for the test.	`-`
`hours`	`integer`	If you want to analyze a period shorter than one day, the number of hours to use for the test.	`-`
`megabytes`	`integer`	The Notecard lifetime data quota (in megabytes) to use for the test.	`1024`

Examples:

Example

{
  "req": "card.usage.test",
  "days": 7,
  "megabytes": 500
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`max`	`integer`	The days of projected data available based on test.	`-`
`days`	`integer`	The number of days used for the test.	`-`
`bytes_per_day`	`integer`	Average bytes per day used during the test period.	`-`
`seconds`	`integer`	Number of seconds in the analyzed period.	`-`
`time`	`integer`	Time of device activation (UNIX Epoch time).	`-`
`bytes_sent`	`integer`	Number of bytes sent by the Notecard to Notehub.	`-`
`bytes_received`	`integer`	Number of bytes received by the Notecard from Notehub.	`-`
`notes_sent`	`integer`	Number of notes sent by the Notecard to Notehub.	`-`
`notes_received`	`integer`	Number of notes received by the Notecard from Notehub.	`-`
`sessions_standard`	`integer`	Number of standard Notehub sessions.	`-`
`sessions_secure`	`integer`	Number of secure Notehub sessions.	`-`

Examples:

Example Response

{
  "max": 12730,
  "days": 7,
  "bytes_per_day": 41136,
  "seconds": 1291377,
  "time": 1598479763,
  "bytes_sent": 163577,
  "bytes_received": 454565,
  "notes_sent": 114,
  "notes_received": 26,
  "sessions_standard": 143,
  "sessions_secure": 31
}

`card.version`

Request

Returns firmware version information for the Notecard.

Parameters:

Parameter	Type	Description	Default
`api`	`integer`	Host expected major version of the Notecard API	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`api`	`integer`	Major version of the Notecard API	`-`
`board`	`string`	Notecard hardware version number	`-`
`body`	`object`	An object containing Notecard firmware details for programmatic access	`-`
`cell`	`boolean`	Notecard supports cellular connectivity	`-`
`device`	`string`	DeviceUID of the Notecard	`-`
`gps`	`boolean`	Notecard has an onboard GPS module	`-`
`name`	`string`	Official name of the device	`-`
`sku`	`string`	Notecard Stock Keeping Unit (SKU)	`-`
`version`	`string`	Complete firmware version of the Notecard	`-`
`wifi`	`boolean`	Notecard supports Wi-Fi connectivity	`-`

`card.voltage`

Request

Provides the current V+ voltage level on the Notecard, and provides information about historical voltage trends. When used with the mode argument, configures voltage thresholds based on how the device is powered.

Parameters:

Parameter	Type	Description	Default
`hours`	`integer`	The number of hours to analyze, up to 720 (30 days)	`-`
`mode`	`string`	Used to set voltage thresholds based on how the Notecard will be powered. Allowed values: `default`, `lipo`, `li`, `alkaline`, `tad`, `lic`	`-`
`vmax`	`number`	Maximum voltage threshold	`-`
`vmin`	`number`	Minimum voltage threshold	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	The current voltage threshold mode	`-`
`usb`	`boolean`	Whether the Notecard is being powered by USB	`-`
`value`	`number`	Current voltage in volts	`-`
`vref`	`number`	Reference voltage in volts	`-`
`vmax`	`number`	Maximum voltage threshold	`-`
`vmin`	`number`	Minimum voltage threshold	`-`
`vhigh`	`number`	High voltage threshold	`-`
`vnormal`	`number`	Normal voltage threshold	`-`
`vlow`	`number`	Low voltage threshold	`-`
`vdead`	`number`	Dead voltage threshold	`-`

`card.wifi`

SKUs

CELL+WIFI WIFI

Request

Sets up a Notecard WiFi to connect to a Wi-Fi access point.

Parameters:

Parameter	Type	Description	Default
`ssid`	`string`	The SSID of the Wi-Fi access point. Alternatively, use `-` to clear an already set SSID.	`-`
`password`	`string`	The network password of the Wi-Fi access point. Alternatively, use `-` to clear an already set password or to connect to an open access point.	`-`
`name`	`string`	By default, the Notecard creates a SoftAP (software enabled access point) under the name "Notecard". You can use the `name` argument to change the name of the SoftAP to a custom name.

If you include a - at the end of the name (for example "name": "acme-"), the Notecard will append the last four digits of the network's MAC address (for example acme-025c). This allows you to distinguish between multiple Notecards in SoftAP mode. | - | | org | string | If specified, replaces the Blues logo on the SoftAP page with the provided name. | - | | start | boolean | Specify true to activate SoftAP mode on the Notecard programmatically. | - | | text | string | A string containing an array of access points the Notecard should attempt to use. The access points should be provided in the following format:

["FIRST-SSID","FIRST-PASSWORD"],["SECOND-SSID","SECOND-PASSWORD"].

You may need to escape any quotes used in this argument before passing it to the Notecard. For example, the following is a valid request to pass to a Notecard through the In-Browser Terminal.

{"req":"card.wifi", "text":"[\"FIRST-SSID\",\"FIRST-PASSWORD\"]"} | - |

Examples:

Set Wi-Fi SSID and password

{
  "req": "card.wifi",
  "ssid": "MyWiFiNetwork",
  "password": "MyPassword123"
}

Start SoftAP mode with custom name

{
  "req": "card.wifi",
  "name": "MyNotecard-",
  "start": true
}

Configure multiple access points using text parameter

{
  "req": "card.wifi",
  "text": "[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-PASSWORD\"]"
}

Clear existing Wi-Fi credentials

{
  "req": "card.wifi",
  "ssid": "-",
  "password": "-"
}

Response

Response containing Wi-Fi connection status and configuration information from the Notecard.

Parameters:

Parameter	Type	Description	Default
`secure`	`boolean`	`true` means that the Wi-Fi access point is using Management Frame Protection.	`-`
`version`	`string`	The Silicon Labs WF200 Wi-Fi Transceiver binary version.	`-`
`ssid`	`string`	The SSID of the Wi-Fi access point.	`-`
`security`	`string`	The security protocol the Wi-Fi access point uses.	`-`

Examples:

Wi-Fi connection status and configuration information

{
  "secure": true,
  "version": "3.12.3",
  "ssid": "<ssid name>",
  "security": "wpa2-psk"
}

`card.wireless`

Request

View the last known network state, or customize the behavior of the modem. Note: Be careful when using this mode with hardware not on hand as a mistake may cause loss of network and Notehub access.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	Network scan mode. Allowed values: `-`, `auto`, `m`, `nb`, `gprs`	`-`
`apn`	`string`	Access Point Name (APN) when using an external SIM	`-`
`method`	`string`	Used when configuring a Notecard to failover to a different SIM. Allowed values: `-`, `dual-primary-secondary`, `dual-secondary-primary`, `primary`, `secondary`	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`status`	`string`	Current network status	`-`
`count`	`integer`	Number of networks found	`-`
`net`	`array`	Array of networks found	`-`

`dfu.get`

Request

Retrieves downloaded firmware data from the Notecard for use with IAP host MCU firmware updates.

Parameters:

Parameter	Type	Description	Default
`length`	`integer`	The number of bytes of firmware data to read and return to the host. Set to `0` to verify that the Notecard is in DFU mode without attempting to retrieve data.	`-`
`offset`	`integer`	The offset to use before performing a read of firmware data.	`-`

Examples:

Retrieves 32 bytes of firmware data from the Notecard, with an offset of 32 bytes.

{
  "req": "dfu.get",
  "length": 32,
  "offset": 32
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`payload`	`string`	A base64 string containing firmware data of the provided `length`.	`-`

Examples:

Returns a base64 string containing firmware data of the provided length.

{
  "payload": "AAAAAAAAAAAAAAAAcy8ACIEvAAgAAAAAjy8ACJ0vAAg="
}

`dfu.status`

Request

Gets and sets the background download status of MCU host or Notecard firmware updates.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Determines which type of firmware update status to view. Allowed values: `user`, `card`	`-`
`stop`	`boolean`	Clear DFU state and delete the local firmware image from the Notecard	`-`
`status`	`string`	Optional string synchronized to Notehub, which can be used for informational or diagnostic purposes	`-`
`version`	`['string', 'object']`	Version information on the host firmware to pass to Notehub	`-`
`vvalue`	`string`	A voltage-variable string that controls, by Notecard voltage, whether or not DFU is enabled	`-`
`on`	`boolean`	Allow firmware downloads from Notehub	`-`
`off`	`boolean`	Disable firmware downloads from Notehub	`-`
`err`	`string`	Sets the host DFU to an error state with the specified string	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	Current DFU mode	`-`
`status`	`string`	Status of the DFU process	`-`
`on`	`boolean`	Whether firmware downloads from Notehub are allowed	`-`
`off`	`boolean`	Whether firmware downloads from Notehub are disabled	`-`
`pending`	`boolean`	Whether a firmware update is pending	`-`
`body`	`object`	Additional information about the DFU status	`-`

`env.default`

Request

Used by the Notecard host to specify a default value for an environment variable until that variable is overridden by a device, project or fleet-wide setting at Notehub.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the environment variable	`-`
`text`	`string`	Default value for the environment variable	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the environment variable	`-`
`text`	`string`	Default value for the environment variable	`-`

`env.get`

Request

Returns a single environment variable, or all variables according to precedence rules.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the environment variable to get	`-`
`names`	`array`	Array of environment variable names to get	`-`
`time`	`boolean`	Return the time when the environment variable was last modified	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the environment variable	`-`
`text`	`string`	Value of the environment variable	`-`
`body`	`object`	Object containing environment variables and their values	`-`
`time`	`integer`	Time when the environment variable was last modified	`-`

`env.modified`

Request

Get the time of the update to any environment variable managed by the Notecard.

Parameters:

Parameter	Type	Description	Default
`time`	`integer`	Request whether the Notecard has detected an environment variable change since a known epoch time	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`time`	`integer`	Time when the environment variables were last modified	`-`

`env.set`

Request

deprecatedThe env.set API is deprecated as of v7.2.2. We recommend setting environment variables in Notehub using either the Notehub user interface or Notehub API. You may also use the env.default API to provide a default value for an environment variable, until that variable is overridden by a value from Notehub.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the environment variable to set	`-`
`text`	`string`	Value to set for the environment variable	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the environment variable	`-`
`text`	`string`	Value of the environment variable	`-`
`time`	`integer`	The logged time of the variable change	`-`

`env.template`

Request

The env.template request allows developers to provide a schema for the environment variables the Notecard uses. The provided template allows the Notecard to store environment variables as fixed-length binary records rather than as flexible JSON objects that require much more memory.

Parameters:

Parameter	Type	Description	Default
`body`	`object`	Template object with environment variable placeholders	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`bytes`	`integer`	Size of the processed template in bytes	`-`

`file.changes`

Request

Used to perform queries on a single or multiple files to determine if new Notes are available to read, or if there are unsynced Notes in local Notefiles.

Parameters:

Parameter	Type	Description	Default
`files`	`array`	One or more files to obtain change information from	`-`
`tracker`	`string`	ID of a change tracker to use to determine changes to Notefiles	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`total`	`integer`	Total number of files	`-`
`changes`	`integer`	Number of files that have changed	`-`
`info`	`object`	Information about the changes	`-`

`file.changes.pending`

Request

Returns info about file changes that are pending upload to Notehub.

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`total`	`integer`	The total of unsynced notes across all Notefiles	`-`
`changes`	`integer`	The number of changes across all files	`-`
`pending`	`boolean`	Whether there are pending changes	`-`
`info`	`object`	Information about changes for each Notefile	`-`

`file.delete`

Request

Deletes Notefiles and the Notes they contain.

Parameters:

Parameter	Type	Description	Default
`files`	`array`	Array of files to delete	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`result`	`object`	Empty object returned on success	`-`

`file.stats`

Request

Gets resource statistics about local Notefiles.

Parameters:

Parameter	Type	Description	Default
`file`	`string`	Optional file to get stats for	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`total`	`integer`	Total number of notes in the file	`-`
`changes`	`integer`	Number of changes to the file	`-`
`sync`	`boolean`	Whether the file is synced with Notehub	`-`

`hub.get`

Request

Retrieves the current Notehub configuration for the Notecard.

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`device`	`string`	The DeviceUID for the Notecard	`-`
`product`	`string`	Product identifier	`-`
`mode`	`string`	Hub mode (periodic, continuous, minimum)	`-`
`outbound`	`integer`	Outbound data period in seconds	`-`
`voutbound`	`string`	Voltage-variable outbound period	`-`
`inbound`	`integer`	Inbound data period in seconds	`-`
`vinbound`	`string`	Voltage-variable inbound period	`-`
`host`	`string`	Host address	`-`
`sn`	`string`	Serial number	`-`
`sync`	`boolean`	Whether sync is enabled	`-`

`hub.log`

Request

Add a "device health" log message to send to Notehub on the next sync via the _health_host.qo Notefile.

Parameters:

Parameter	Type	Description	Default
`text`	`string`	Text to log	`-`
`alert`	`boolean`	Whether this is an alert message	`-`
`sync`	`boolean`	Whether to sync this log message immediately	`-`

Response

No description available.

No specific parameters defined.

`hub.set`

Request

The hub.set request is the primary method for controlling the Notecard's Notehub connection and sync behavior.

Parameters:

Parameter	Type	Description	Default
`product`	`string`	Product identifier	`-`
`host`	`string`	Host address	`-`
`mode`	`string`	Hub mode (periodic, continuous, minimum, off). Allowed values: `continuous`, `periodic`, `minimum`, `off`	`-`
`sn`	`string`	Serial number	`-`
`outbound`	`integer`	Outbound data period in seconds	`-`
`duration`	`integer`	Duration of the outbound period in seconds	`-`
`voutbound`	`string`	Voltage-variable outbound period	`-`
`inbound`	`integer`	Inbound data period in seconds	`-`
`vinbound`	`string`	Voltage-variable inbound period	`-`
`align`	`boolean`	Whether to align the inbound and outbound periods	`-`
`sync`	`boolean`	Whether to sync immediately	`-`
`on`	`boolean`	Whether to turn on the hub	`-`
`seconds`	`integer`	Number of seconds to wait before turning off	`-`
`off`	`boolean`	Whether to turn off the hub	`-`
`uperiodic`	`integer`	Microseconds for periodic mode	`-`
`umin`	`integer`	Microseconds for minimum mode	`-`
`uoff`	`integer`	Microseconds for off mode	`-`
`details`	`boolean`	Whether to include details in the response	`-`
`version`	`['string', 'object']`	Version information	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`result`	`object`	Empty object returned on success	`-`

`hub.signal`

Request

Receive a signal (a near-real-time note) from Notehub.

Parameters:

Parameter	Type	Description	Default
`seconds`	`integer`	Number of seconds to wait for a signal	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`body`	`object`	Signal information	`-`
`connected`	`boolean`	Whether the Notecard is connected to the network	`-`
`signals`	`array`	Array of signal information	`-`

`hub.status`

Request

Displays the current status of the Notecard's connection to Notehub.

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`status`	`string`	Hub connection status	`-`
`connected`	`boolean`	Whether the Notecard is connected to the hub	`-`

`hub.sync`

Request

Manually initiates a sync with Notehub.

Parameters:

Parameter	Type	Description	Default
`allow`	`boolean`	Whether to allow the sync to proceed	`-`
`out`	`boolean`	Whether to sync outbound data	`-`
`in`	`boolean`	Whether to sync inbound data	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`result`	`object`	Empty object returned on success	`-`

`hub.sync.status`

Request

Check on the status of a recently triggered or previous sync.

Parameters:

Parameter	Type	Description	Default
`sync`	`boolean`	Whether to sync immediately	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`status`	`string`	Status of the sync operation	`-`
`mode`	`string`	Current sync mode	`-`
`time`	`integer`	Time of the last sync	`-`
`alert`	`string`	Alert message	`-`
`sync`	`boolean`	Whether a sync is in progress	`-`
`completed`	`boolean`	Whether the sync has completed	`-`
`requested`	`boolean`	Whether a sync has been requested	`-`
`seconds`	`integer`	Number of seconds since the last sync	`-`
`scan`	`boolean`	Whether a scan is in progress	`-`

`note.add`

Request

Adds a Note to a Notefile, creating the Notefile if it doesn't yet exist.

Parameters:

Parameter	Type	Description	Default
`file`	`string`	Name of the notefile to add the note to	`-`
`note`	`object`	Note data to add	`-`
`body`	`object`	Note body data	`-`
`payload`	`string`	Binary payload data	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`note`	`string`	ID of the added note	`-`

`note.changes`

Request

Used to incrementally retrieve changes within a specific Notefile.

Parameters:

Parameter	Type	Description	Default
`file`	`string`	Name of the notefile to check for changes	`-`
`tracker`	`string`	Tracker ID for monitoring changes	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`changes`	`boolean`	Whether there are changes	`-`
`notes`	`array`	Array of note IDs that have changed	`-`
`tracker`	`string`	Tracker ID for monitoring changes	`-`

`note.delete`

Request

Deletes a Note from a DB Notefile by its Note ID. To delete Notes from a .qi Notefile, use note.get or note.changes with delete:true.

Parameters:

Parameter	Type	Description	Default
`file`	`string`	Name of the notefile to delete notes from	`-`
`note`	`string`	ID of the note to delete	`-`
`notes`	`array`	Array of note IDs to delete	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`success`	`boolean`	Whether the deletion was successful	`-`

`note.get`

Request

Retrieves a Note from a Notefile. The file must either be a DB Notefile or inbound queue file (see file argument below).

Parameters:

Parameter	Type	Description	Default
`file`	`string`	Name of the notefile to get the note from	`-`
`note`	`string`	ID of the note to get	`-`
`delete`	`boolean`	Whether to delete the note after getting it	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`note`	`string`	ID of the note	`-`
`body`	`object`	Note body data	`-`
`payload`	`string`	Binary payload data	`-`

`note.template`

Request

By using the note.template request with any .qo/.qos Notefile, developers can provide the Notecard with a schema of sorts to apply to future Notes added to the Notefile. This template acts as a hint to the Notecard that allows it to internally store data as fixed-length binary records rather than as flexible JSON objects which require much more memory. Using templated Notes in place of regular Notes increases the storage and sync capability of the Notecard by an order of magnitude.

Parameters:

Parameter	Type	Description	Default
`file`	`string`	Name of the notefile to add the note to	`-`
`template`	`object`	Template for the note	`-`
`body`	`object`	Template for the note body	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`success`	`boolean`	Whether the template was set successfully	`-`

`note.update`

Request

Updates a Note in a DB Notefile by its ID, replacing the existing body and/or payload.

Parameters:

Parameter	Type	Description	Default
`file`	`string`	Name of the notefile to update the note in	`-`
`note`	`string`	ID of the note to update	`-`
`body`	`object`	Updated note body data	`-`
`payload`	`string`	Updated binary payload data	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`success`	`boolean`	Whether the update was successful	`-`

`ntn.gps`

Request

Determines whether a Notecard should override a paired Starnote's GPS/GNSS location with its own GPS/GNSS location. The paired Starnote uses its own GPS/GNSS location by default.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	GPS mode. Allowed values: `continuous`, `periodic`, `off`	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`mode`	`string`	Current GPS mode	`-`

`ntn.reset`

Request

Once a Notecard is connected to a Starnote device, the presence of a physical Starnote is stored in a permanent configuration that is not affected by a card.restore request. This request clears this configuration and allows you to return to testing NTN mode over cellular or Wi-Fi.

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`success`	`boolean`	Whether the reset was successful	`-`

`ntn.status`

Request

Displays the current status of a Notecard's connection to a paired Starnote.

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`status`	`string`	Status of the Notehub connection	`-`
`connected`	`boolean`	Whether the Notecard is connected to Notehub	`-`
`time`	`integer`	Current time (Unix epoch seconds)	`-`

`var.delete`

Request

Delete a Note from a DB Notefile by its name. Provides a simpler interface to the note.delete API.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the variable to delete	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`success`	`boolean`	Whether the variable was successfully deleted	`-`

`var.get`

Request

Retrieves a Note from a DB Notefile. Provides a simpler interface to the note.get API.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the variable to get	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the variable	`-`
`text`	`string`	Value of the variable	`-`

`var.set`

Request

Adds or updates a Note in a DB Notefile, replacing the existing body with the specified key-value pair where text, value, or flag is the key. Provides a simpler interface to the note.update API.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the variable to set	`-`
`text`	`string`	Value to set for the variable	`-`

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`name`	`string`	Name of the variable	`-`
`text`	`string`	Value of the variable	`-`

`web`

Request

JSON description of the web API

Parameters:

Parameter	Type	Description	Default
`route`	`string`	Alias for a Proxy Route in Notehub.	`-`
`method`	`string`	The HTTP method of the request. Must be one of GET, PUT, POST, DELETE, PATCH, HEAD, OPTIONS, TRACE, or CONNECT.. Allowed values: `CONNECT`, `DELETE`, `GET`, `HEAD`, `OPTIONS`, `PATCH`, `POST`, `PUT`, `TRACE`	`-`
`name`	`string`	A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. `/getLatest?id=1`).	`-`
`content`	`string`	The MIME type of the body or payload of the response. Default is `application/json`.	`-`

Examples:

Get the current time

{
  "req": "web",
  "method": "GET",
  "route": "weatherInfo",
  "name": "/getLatest"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`result`	`integer`	The HTTP Status Code	`-`
`body`	`object`	The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.	`-`
`payload`	`string`	A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.	`-`
`length`	`integer`	The length of the returned binary payload (in bytes).	`-`
`cobs`	`integer`	The size of the COBS-encoded data (in bytes).	`-`

Examples:

Response from a web request

{
  "result": 200,
  "body": {
    "temp": 75,
    "humidity": 49
  }
}

`web.delete`

SKUs

CELL CELL+WIFI WIFI

Request

Performs a simple HTTP or HTTPS DELETE request against an external endpoint, and returns the response to the Notecard.

Parameters:

Parameter	Type	Description	Default
`route`	`string`	Alias for a Proxy Route in Notehub.	`-`
`name`	`string`	A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. `/deleteReading?id=1`).	`-`
`content`	`string`	The MIME type of the body or payload of the response. Default is `application/json`.	`application/json`
`seconds`	`integer`	If specified, overrides the default 90 second timeout.	`90`
`async`	`boolean`	If `true`, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub.	`-`
`file`	`string`	The name of the local-only Database Notefile (`.dbx`) to be used if the web request is issued asynchronously and you wish to store the response.	`-`
`note`	`string`	The unique Note ID for the local-only Database Notefile (`.dbx`). Only used with asynchronous web requests (see `file` argument above).	`-`

Examples:

Example

{
  "req": "web.delete",
  "route": "SensorService",
  "name": "/deleteReading?id=1"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`result`	`integer`	The HTTP Status Code	`-`
`body`	`object`	The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.	`-`
`payload`	`string`	A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.	`-`
`status`	`string`	If a `payload` is returned in the response, this is a 32-character hex-encoded MD5 sum of the payload or payload fragment. Useful for the host to check for any I2C/UART corruption.	`-`

Examples:

Example Response

{
  "result": 204
}

`web.get`

SKUs

CELL CELL+WIFI WIFI

Request

Performs a simple HTTP or HTTPS GET request against an external endpoint, and returns the response to the Notecard.

Parameters:

Parameter	Type	Description	Default
`route`	`string`	Alias for a Proxy Route in Notehub.	`-`
`name`	`string`	A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. `/getLatest?id=1`).	`-`
`body`	`object`	The JSON body to send with the request.	`-`
`content`	`string`	The MIME type of the body or payload of the response. Default is `application/json`.	`-`
`seconds`	`integer`	If specified, overrides the default 90 second timeout.	`-`
`async`	`boolean`	If `true`, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub.	`-`
`binary`	`boolean`	If `true`, the Notecard will return the response stored in its binary buffer.	`-`
`offset`	`integer`	Used along with `binary:true` and `max`, sent as a URL parameter to the remote endpoint. Represents the number of bytes to offset the binary payload from 0 when retrieving binary data from the remote endpoint.	`-`
`max`	`integer`	Used along with `binary:true` and `offset`, sent as a URL parameter to the remote endpoint. Represents the number of bytes to retrieve from the binary payload segment.	`-`
`file`	`string`	The name of the local-only Database Notefile (`.dbx`) to be used if the web request is issued asynchronously and you wish to store the response.	`-`
`note`	`string`	The unique Note ID for the local-only Database Notefile (`.dbx`). Only used with asynchronous web requests (see `file` argument above).	`-`

Examples:

Performs a simple HTTP or HTTPS GET request and returns the response.

{
  "req": "web.get",
  "route": "weatherInfo",
  "name": "/getLatest"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`result`	`integer`	The HTTP Status Code.	`-`
`body`	`object`	The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.	`-`
`payload`	`string`	A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.	`-`
`length`	`integer`	The length of the returned binary payload (in bytes).	`-`
`cobs`	`integer`	The size of the COBS-encoded data (in bytes).	`-`

Examples:

Response body from HTTP GET request to the external service.

{
  "result": 200,
  "body": {
    "temp": 75,
    "humidity": 49
  }
}

`web.post`

SKUs

CELL CELL+WIFI WIFI

Request

Performs a simple HTTP or HTTPS POST request against an external endpoint, and returns the response to the Notecard.

Parameters:

Parameter	Type	Description	Default
`route`	`string`	Alias for a Proxy Route in Notehub.	`-`
`name`	`string`	A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. `/addReading?id=1`).	`-`
`body`	`object`	The JSON body to send with the request.	`-`
`payload`	`string`	A base64-encoded binary payload. A `web.post` may have either a `body` or a `payload`, but may NOT have both. Be aware that Notehub will decode the payload as it is delivered to the endpoint.

Examples:

Example

{
  "req": "web.post",
  "route": "SensorService",
  "name": "/addReading",
  "body": {
    "temp": 72.32,
    "humidity": 32.2
  }
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`result`	`integer`	The HTTP Status Code.	`-`
`body`	`object`	The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.	`-`
`payload`	`string`	A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.	`-`
`status`	`string`	If a `payload` is returned in the response, this is a 32-character hex-encoded MD5 sum of the payload or payload fragment. Useful for the host to check for any I2C/UART corruption.	`-`
`cobs`	`integer`	If the web transaction returns a binary payload, `cobs` is the size of the COBS-encoded payload (in bytes).	`-`
`length`	`integer`	If the web transaction returns a binary payload, `length` is the size of the unencoded payload (in bytes).	`-`

Examples:

Example Response

{
  "result": 201
}

`web.put`

SKUs

CELL CELL+WIFI WIFI

Request

Performs a simple HTTP or HTTPS PUT request against an external endpoint, and returns the response to the Notecard.

Parameters:

Parameter	Type	Description	Default
`route`	`string`	Alias for a Proxy Route in Notehub.	`-`
`name`	`string`	A web URL endpoint relative to the host configured in the Proxy Route. URL parameters may be added to this argument as well (e.g. `/updateReading?id=1`).	`-`
`body`	`object`	The JSON body to send with the request.	`-`
`payload`	`string`	A base64-encoded binary payload. A `web.put` may have either a `body` or a `payload`, but may NOT have both. Be aware that Notehub will decode the payload as it is delivered to the endpoint.

Examples:

Performs a simple HTTP or HTTPS PUT request and returns the response.

{
  "req": "web.put",
  "route": "SensorService",
  "name": "/updateReading",
  "body": {
    "id": 1234,
    "temp": 72.32,
    "humidity": 32.2
  }
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
`result`	`integer`	The HTTP Status Code.	`-`
`body`	`object`	The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.	`-`
`payload`	`string`	A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.	`-`
`status`	`integer`	If a `payload` is returned in the response, this is a 32-character hex-encoded MD5 sum of the payload or payload fragment. Useful for the host to check for any I2C/UART corruption.	`-`

Examples:

Example Response

{
  "result": 204
}