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"}

card.attn

Version Information

Schema Version: 0.1.2 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Configure hardware notifications from a Notecard to a host MCU.

NOTE: Requires a connection between the Notecard ATTN pin and a GPIO pin on the host MCU.

Parameters:

Parameter	Type	Description	Default
files	array	A list of Notefiles to watch for file-based interrupts.	-
mode	string	A comma-separated list of one or more of the following keywords. Some keywords are only supported on certain types of Notecards. Allowed Values: "": Fetches currently pending events in the "files" collection. (CELL, CELL+WIFI, WIFI) "arm": Clear "files" events and cause the ATTN pin to go LOW. After an event occurs or "seconds" has elapsed, the ATTN pin will then go HIGH (a.k.a. "fires"). If "seconds" is 0, no timeout will be scheduled. If ATTN is armed, calling arm again will disarm (briefly pulling ATTN HIGH), then arm (non-idempotent). (CELL, CELL+WIFI, LORA, WIFI) "auxgpio": When armed, causes ATTN to fire if an AUX GPIO input changes. Disable by using -auxgpio. (CELL, CELL+WIFI, LORA, WIFI) "connected": When armed, will cause ATTN to fire whenever the module connects to cellular. Disable with -connected. (CELL, CELL+WIFI, WIFI) "disarm": Causes ATTN pin to go HIGH if it had been LOW. Passing both "disarm" and "-all" clears all ATTN monitors currently set. (CELL, CELL+WIFI, LORA, WIFI) "env": When armed, causes ATTN to fire if an environment variable changes on the Notecard. Disable by using -env. (CELL, CELL+WIFI, LORA, WIFI) "files": When armed, will cause ATTN to fire if any of the "files" are modified. Disable by using -files. (CELL, CELL+WIFI, LORA, WIFI) "location": When armed, will cause ATTN to fire whenever the Notecard GPS module makes a position fix. Disable by using -location. (CELL, CELL+WIFI, WIFI) "motion": When armed, will cause ATTN to fire whenever the accelerometer detects module motion. Disable with -motion. (CELL, CELL+WIFI, WIFI) "motionchange": When armed, will cause ATTN to fire whenever the card.motion.mode changes from "moving" to "stopped" (or vice versa). Learn how to configure this feature in this guide. (CELL, CELL+WIFI, WIFI) "rearm": Will arm ATTN if not already armed. Otherwise, resets the values of mode, files, and seconds specified in the initial arm or rearm request (idempotent). (CELL, CELL+WIFI, WIFI) "signal": When armed, will cause ATTN to fire whenever the Notecard receives a signal. (CELL, CELL+WIFI, WIFI) "sleep": Instruct the Notecard to pull the ATTN pin low for a period of time, and optionally keep a payload in memory. Can be used by the host to sleep the host MCU. (CELL, CELL+WIFI, WIFI) "usb": When armed, will enable USB power events firing the ATTN pin. Disable with -usb. (CELL, CELL+WIFI, LORA, WIFI) "watchdog": Not an "arm" mode, rather will cause the ATTN pin to go from HIGH to LOW, then HIGH if the notecard fails to receive any JSON requests for "seconds." In this mode, "seconds" must be >= 60. (CELL, CELL+WIFI, WIFI) "wireless": Instruct the Notecard to fire the ATTN pin whenever the card.wireless status changes. (CELL, CELL+WIFI, WIFI)	-
off	boolean	When true, completely disables ATTN processing and sets the pin OFF. This setting is retained across device restarts.	-
on	boolean	When true, enables ATTN processing. This setting is retained across device restarts.	-
payload	string	When using sleep mode, a payload of data from the host that the Notecard should hold in memory until retrieved by the host.	-
seconds	integer	To set an ATTN timeout when arming, or when using sleep. NOTE: When the Notecard is in continuous mode, the seconds timeout is serviced by a routine that wakes every 15 seconds. You can predict when the device will wake, by rounding up to the nearest 15 second interval._	-
start	boolean	When using sleep mode and the host has reawakened, request the Notecard to return the stored payload.	-
verify	boolean	When true, returns the current attention mode configuration, if any.	-

Examples:

Configure the Notecard to perform an interrupt on a successful connection to Notehub.

{
  "req": "card.attn",
  "mode": "arm,connected"
}

Configure the Notecard to perform an interrupt on the data.qi and my-settings.db Notefiles.

{
  "req": "card.attn",
  "mode": "arm,files",
  "files": [
    "data.qi",
    "my-settings.db"
  ]
}

Configure the Notecard to perform an interrupt when the Notecard makes a position fix.

{
  "req": "card.attn",
  "mode": "arm,location"
}

Configure the Notecard to perform an interrupt when the Notecard detects motion.

{
  "req": "card.attn",
  "mode": "arm,motion"
}

Configure the Notecard to perform an interrupt when the Notecard receives a signal.

{
  "req": "card.attn",
  "mode": "arm,signal"
}

Configure the Notecard to function as a watchdog timer with a 60 second timeout.

{
  "req": "card.attn",
  "mode": "watchdog",
  "seconds": 60
}

Configure the Notecard to instruct the host MCU to sleep for a period of time.

{
  "req": "card.attn",
  "mode": "sleep",
  "seconds": 3600,
  "payload": "ewogICJpbnRlcnZhbHMiOiI2MCwxMiwxNCIKfQ=="
}

Retrieve a payload from the Notecard after sleep.

{
  "req": "card.attn",
  "start": true
}

Disarm all interrupts.

{
  "req": "card.attn",
  "mode": "disarm,-all"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
files	array	A list of files changed since file attention mode was set. In addition, this field will include keywords to signify the occurrence of other attention mode triggers:	-
off	boolean	This field is present and set to true if ATTN processing has been disabled with the off argument.	-
payload	string	When using sleep mode with a payload, the payload provided by the host to the Notecard.	-
set	boolean	Reflects the state of the attention pin. The set field is true when the attention pin is HIGH, otherwise the set field will not be present when the attention pin is LOW.	-
time	integer	When using sleep mode with a payload, the time (UNIX Epoch time) that the payload was stored by the Notecard.	-

Examples:

Example Response

{
  "files": [
    "data.qi",
    "modified"
  ],
  "set": true
}

card.aux

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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
connected	boolean	If true, defers the sync of the state change Notefile to the next sync as configured by the hub.set request.	-
count	integer	When used with "mode":"neo-monitor" or "mode":"track-neo-monitor", this controls the number of NeoPixels to use in a strip. Possible values are 1, 2, or 5.. Allowed values: 1, 2, 5	-
file	string	The name of the Notefile used to report state changes when used in conjunction with "sync": true. Default Notefile name is _button.qo.	-
gps	boolean	If true, along with "mode":"track" the Notecard supports the use of an external GPS module. This argument is deprecated. Use the card.aux.serial request with a mode of "gps" instead.	-
limit	boolean	If true, along with "mode":"track" and gps:true the Notecard will disable concurrent modem use during GPS tracking.	-
max	integer	When in gpio mode, if an AUX pin is configured as a count type, the maximum number of samples of duration seconds, after which all subsequent counts are added to the final sample. Passing 0 or omitting this value will provide a single incrementing count of rising edges on the pin.	-
mode	string	The AUX mode. Must be one of the following keywords. Some keywords are only supported on certain types of Notecards. Allowed Values: "dfu": Enable the Notecard's AUX1 pin for Outboard Firmware Updates. When enabled, AUX1 is active LOW when a DFU is in progress, and HIGH otherwise. See Using DFU Mode for more information. (CELL, CELL+WIFI, WIFI) "gpio": Configure the Notecard for GPIO mode with AUX1 OFF, AUX2 as an output LOW, AUX3 as an output HIGH, and AUX4 as an input. (CELL, CELL+WIFI, LORA, WIFI) "led": When wiring LEDs to the Notecard's AUX pins (as is done when using monitor mode), use this mode along with the card.led API to manually enable/disable individual red, green, and/or yellow LEDs. (CELL, CELL+WIFI, WIFI) "monitor": If you plan to place your Notecard in an enclosure, monitor mode can be used to configure inputs and outputs typically placed on the faceplate of a device in order for a technician to test and monitor Notecard activity. (CELL, CELL+WIFI, WIFI) "motion": Supplement autonomous tracking with digital inputs and a status output. (CELL, CELL+WIFI, WIFI) "neo": When wiring a NeoPixel or NeoPixel strip to the Notecard's AUX2 pin (as is done when using neo-monitor mode), use this mode along with the card.led API to manually enable/disable a single NeoPixel. (CELL, CELL+WIFI, WIFI) "neo-monitor": Similar to monitor mode, neo-monitor mode supports NeoPixel LEDs that can be used to configure inputs and outputs typically placed on the faceplate of a device in order for a technician to test and monitor Notecard activity. (CELL, CELL+WIFI, LORA, WIFI) "off": Disable AUX mode. (CELL, CELL+WIFI, LORA, WIFI) "track": Enhance Notes in the _track.qo Notefile with temperature, pressure, and humidity readings from a connected BME280 sensor. (CELL, CELL+WIFI, WIFI) "track-monitor": Combines the functionality of the track and monitor AUX modes. (CELL, CELL+WIFI, WIFI) "track-neo-monitor": Combines track and monitor modes while also supporting NeoPixel LEDs that allow for monitoring Notecard activity. (CELL, CELL+WIFI, WIFI) "-": Resets the AUX mode to its default value (off). (CELL, CELL+WIFI, LORA, WIFI)	-
ms	integer	When in gpio mode, this argument configures a debouncing interval. With a debouncing interval in place, the Notecard excludes all transitions with a shorter duration than the provided debounce time, in milliseconds. This interval only applies to GPIOs configured with a usage of count, count-pulldown, or count-pullup.	-
offset	integer	When used with "mode":"neo-monitor" or "mode":"track-neo-monitor", this is the 1-based index in a strip of NeoPixels that determines which single NeoPixel the host can command.	-
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
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. Passing 0 or omitting this field will total into a single sample.	-
sensitivity	integer	When used with "mode":"neo-monitor" or "mode":"track-neo-monitor", this controls the brightness of NeoPixel lights, where 100 is the maximum brightness and 1 is the minimum.	-
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.	-
sync	boolean	If true, for pins set as input by usage, the Notecard will autonomously report any state changes as new notes in file. For pins used as counter, the Notecard will use an interrupt to count pulses and will report the total in a new note in file unless it has been noted in the previous second.	-
usage	array	An ordered list of pin modes for each AUX pin when in GPIO mode. Allowed Values: "": to leave the pin unchanged. (CELL, CELL+WIFI, LORA, WIFI) "off": to disable the pin. (CELL, CELL+WIFI, LORA, WIFI) "high": to set the pin as a HIGH output. (CELL, CELL+WIFI, LORA, WIFI) "low": to set the pin as a LOW output. (CELL, CELL+WIFI, LORA, WIFI) "input": to set the pin as an input. (CELL, CELL+WIFI, LORA, WIFI) "input-pulldown": to set the pin as a pull-down input. (CELL, CELL+WIFI, LORA, WIFI) "input-pullup": to set the pin as a pull-up input. (CELL, CELL+WIFI, LORA, WIFI) "count": to set the pin as an input (interrupt) that increments a counter for each rising edge pulse on the pin. It is up to the device's designer to make sure that the signal is either HIGH or LOW at any time, and is never left floating. (CELL, CELL+WIFI, WIFI) "count-pulldown": Same as count usage, but a pull-down resistor internal to the Notecard will automatically keep the pin from floating. (CELL, CELL+WIFI, WIFI) "count-pullup": Same as count usage, but a pull-up resistor internal to the Notecard will automatically keep the pin from floating and falling edges of pulses are counted. (CELL, CELL+WIFI, WIFI)	-

Examples:

Enable the Notecard's AUX1 pin for Outboard Firmware Updates. When enabled, AUX1 is active LOW when a DFU is in progress, and HIGH otherwise.

{
  "req": "card.aux",
  "mode": "dfu"
}

Configure the Notecard for GPIO mode with AUX1 OFF, AUX2 as an output LOW, AUX3 as an output HIGH, and AUX4 as an input.

{
  "req": "card.aux",
  "mode": "gpio",
  "usage": [
    "off",
    "low",
    "high",
    "input"
  ]
}

Configure the Notecard for GPIO mode with AUX1 OFF, AUX2 as an output LOW, AUX3 as an output HIGH, and AUX4 as a count.

{
  "req": "card.aux",
  "mode": "gpio",
  "usage": [
    "off",
    "low",
    "high",
    "count"
  ],
  "seconds": 2,
  "max": 5,
  "start": true
}

Configure GPIO mode with automatic state change reporting to a Notefile.

{
  "req": "card.aux",
  "mode": "gpio",
  "usage": [
    "off",
    "low",
    "high",
    "input"
  ],
  "sync": true,
  "file": "statechange.qo"
}

Configure inputs and outputs typically placed on the faceplate of a device for technicians to test and monitor Notecard activity.

{
  "req": "card.aux",
  "mode": "monitor"
}

Enable neo-monitor mode which supports NeoPixel LEDs for monitoring Notecard activity.

{
  "req": "card.aux",
  "mode": "neo-monitor"
}

Supplement autonomous tracking with digital inputs and a status output.

{
  "req": "card.aux",
  "mode": "motion"
}

Configure the AUX UART baud rate for debug communication.

{
  "req": "card.aux",
  "rate": 9600
}

Enhance Notes with temperature, pressure, and humidity readings from a connected BME280 sensor.

{
  "req": "card.aux",
  "mode": "track"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
mode	string	The current AUX mode, or off if not set.	-
power	boolean	If true, indicates the Notecard has USB (main) power. This parameter only appears in the body of the Note in Notehub if using "sync":true.	-
seconds	integer	When in AUX gpio mode, and if count is enabled on an AUX pin, the number of seconds per sample.	-
state	array	When in AUX gpio mode, the state of each AUX pin. Allowed Values: "": {} when the pin is off. (CELL, CELL+WIFI, LORA, WIFI) "high": {"high": true} when the pin is high. (CELL, CELL+WIFI, LORA, WIFI) "low": {"low": true} when the pin is low. (CELL, CELL+WIFI, LORA, WIFI) "input": {"input": true} when the pin is input. (CELL, CELL+WIFI, LORA, WIFI) "count": {"count": [4]} where each item in the array is the count per sample. (CELL, CELL+WIFI, WIFI)	-
time	integer	When in AUX gpio mode, and if count is enabled on an AUX pin, the time that counting started.	-

Examples:

Example response showing GPIO mode configuration with pin states.

{
  "mode": "gpio",
  "state": [
    {},
    {
      "low": true
    },
    {
      "high": true
    },
    {
      "count": [
        3
      ]
    }
  ],
  "time": 1592587637,
  "seconds": 2
}

card.aux.serial

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
duration	integer	If using "mode": "accel", specify a sampling duration for the Notecard accelerometer.	-
limit	boolean	If true, along with "mode":"gps" the Notecard will disable concurrent modem use during GPS tracking.	-
max	integer	The maximum amount of data to send per session, in bytes. This is typically set to the size of the receive buffer on the host minus 1. For example, note-arduino uses a buffer size of (SERIAL_RX_BUFFER_SIZE - 1).	-
minutes	integer	When using "mode": "notify,dfu", specify an interval for notifying the host.	-
mode	string	The AUX mode. Must be one of the following: Allowed Values: "req": (Default) for request/response monitoring on the AUX pins. "gps": Use an external GPS/GNSS module on the AUX pins. Using an external GPS/GNSS module allows you to acquire GPS/GNSS location while Notecard is connected to Notehub in continuous mode. Learn more at Using AUX Serial GPS Mode. "notify": Used along with one or more of the notify options to send streaming data or notification data over the AUX pins. When used alone, preserves existing notification settings. "notify,accel": Used to stream readings from the onboard accelerometer over AUX. "notify,signals": Used to notify the host of any Inbound Signals from Notehub. "notify,env": Used to notify the host of Environment Variable changes over AUX. "notify,dfu": Used to notify the host that the Notecard has downloaded updated host firmware.	-
ms	integer	The delay in milliseconds before sending a buffer of max size.	-
rate	integer	The baud rate or speed at which information is transmitted over AUX serial. The default is 115200 unless using GPS, in which case the default is 9600.	-

Examples:

Configure AUX serial for external GPS communication. Using an external GPS/GNSS module allows you to acquire GPS/GNSS location while Notecard is connected to Notehub in continuous mode. Learn more at Using AUX Serial GPS Mode.

{
  "req": "card.aux.serial",
  "mode": "gps"
}

Configure AUX serial for DFU notifications with timeout.

{
  "req": "card.aux.serial",
  "mode": "notify,dfu",
  "minutes": 5
}

Configure AUX serial for environment variable change notifications.

{
  "req": "card.aux.serial",
  "mode": "notify,env"
}

Set AUX serial to request mode for command/response communication.

{
  "req": "card.aux.serial",
  "mode": "req"
}

Send raw readings from the onboard accelerometer over AUX every 500 ms.

{
  "req": "card.aux.serial",
  "mode": "notify,accel",
  "duration": 500
}

Turn on Inbound Signals from Notehub for low-latency communication.

{
  "req": "card.aux.serial",
  "mode": "notify,signals"
}

Subscribe to multiple notifications at once.

{
  "req": "card.aux.serial",
  "mode": "notify,accel,env",
  "duration": 500
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
mode	string	The current AUX mode.	-
rate	integer	The baud rate or speed at which information is transmitted over AUX serial.	-

Examples:

Example response showing current AUX serial configuration.

{
  "mode": "req",
  "rate": 115200
}

card.binary

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

View the status of the binary storage area of the Notecard and optionally clear any data and related card.binary variables. See the guide on Sending and Receiving Large Binary Objects for best practices when using card.binary.

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.	-

Examples:

Check the status of binary storage area.

{
  "req": "card.binary"
}

Clear the COBS area and reset binary variables.

{
  "req": "card.binary",
  "delete": true
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
cobs	integer	The size of COBS-encoded data stored in the reserved area (without the trailing ).	-
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 amount of unencoded data currently stored (in bytes).	-
max	integer	The space available (in bytes) for storing unencoded data on the Notecard.	-
status	string	The MD5 checksum calculated for the entire unencoded buffer.	-

Examples:

Example response showing binary storage status.

{
  "connected": true,
  "max": 130554,
  "status": "ce6fdef565eeecf14ab38d83643b922d",
  "length": 4,
  "cobs": 5
}

card.binary.get

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

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.

See the guide on Sending and Receiving Large Binary Objects for best practices when using card.binary.

Parameters:

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

Examples:

Retrieve all binary data from storage area.

{
  "req": "card.binary.get"
}

Response

No description available.

Parameters:

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

Examples:

Example response with MD5 checksum.

{
  "status": "ce6fdef565eeecf14ab38d83643b922d"
}

card.binary.put

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

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.

See the guide on Sending and Receiving Large Binary Objects for best practices when using card.binary.

Parameters:

Parameter	Type	Description	Default
cobs	integer	The size of the COBS-encoded data (in bytes).	-
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. Primarily used when sending multiple fragments of one binary payload to the Notecard.	-
status	string	The MD5 checksum of the data, before it has been encoded.	-

Examples:

Send binary data with MD5 checksum.

{
  "req": "card.binary.put",
  "cobs": 5,
  "status": "ce6fdef565eeecf14ab38d83643b922d"
}

Response

No description available.

Parameters:

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

card.carrier

Version Information

Schema Version: 0.2.3 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

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
charging	boolean	Will display true when in AUX_CHARGING "charging" mode.	-
mode	string	The current AUX_CHARGING mode, or off if not set.	-

Examples:

Example response showing charging mode status.

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

card.contact

Version Information

Schema Version: 0.2.2 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
email	string	Set the email address of the Notecard maintainer.	-
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.	-

Examples:

Set contact information for the Notecard maintainer.

{
  "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
email	string	Email address of the Notecard maintainer.	-
name	string	Name of the Notecard maintainer.	-
org	string	Organization name of the Notecard maintainer.	-
role	string	Role of the Notecard maintainer.	-

Examples:

Example response showing contact information.

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

card.dfu

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Used to configure a Notecard for Notecard Outboard Firmware Update.

Parameters:

Parameter	Type	Description	Default
mode	string	The mode argument allows you to control whether a Notecard's AUX pins (default) or ALT_DFU pins are used for Notecard Outboard Firmware Update. This argument is only supported on Notecards that have ALT_DFU pins, which includes all versions of Notecard Cell+WiFi, non-legacy versions of Notecard Cellular, and Notecard WiFi v2. Allowed Values: "altdfu": Enable the Notecard's ALT_DFU pins (instead of the AUX pins) for use with Notecard Outboard Firmware Update. "off": Return the Notecard's ALT_DFU pins to their default state.	-
name	string	One of the supported classes of host MCU. Supported MCU classes are "esp32", "stm32", "stm32-bi", "mcuboot" (added in v5.3.1), and "-", which resets the configuration. The "bi" in "stm32-bi" stands for "boot inverted", and the "stm32-bi" option should be used on STM32 family boards where the hardware boot pin is assumed to be active low, instead of active high. Supported MCUs can be found on the Notecarrier F datasheet. Allowed Values: "esp32": ESP32 microcontroller family. "stm32": STM32 microcontroller family. "stm32-bi": STM32 microcontroller family with boot inverted (boot pin active low). "mcuboot": MCUboot compatible microcontroller (added in v5.3.1). "-": Resets the configuration.	-
off	boolean	Set to true to disable Notecard Outboard Firmware Update from occurring.	-
on	boolean	Set to true to enable Notecard Outboard Firmware Update.	-
seconds	integer	When used with "off":true, disable Notecard Outboard Firmware Update operations for the specified number of seconds.	-
start	boolean	Set to true to enable the host RESET if previously disabled with "stop":true.	-
stop	boolean	Set to true to disable the host RESET that is normally performed on the host MCU when the Notecard starts up (in order to ensure a clean startup), and also when the Notecard wakes up the host MCU after the expiration of a card.attn "sleep" operation. If true, the host MCU will not be reset in these two conditions.	-

Examples:

Enable DFU for STM32 microcontroller.

{
  "req": "card.dfu",
  "name": "stm32",
  "on": true
}

Enable DFU for ESP32 microcontroller.

{
  "cmd": "card.dfu",
  "name": "esp32",
  "on": true
}

Use ALT_DFU pins instead of AUX pins on Cell+WiFi.

{
  "req": "card.dfu",
  "mode": "altdfu"
}

Disable DFU for 3600 seconds.

{
  "req": "card.dfu",
  "off": true,
  "seconds": 3600
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
name	string	The class of MCU that the Notecard is currently configured to support for Outboard DFU.	-

Examples:

Example response showing current DFU configuration.

{
  "name": "stm32"
}

card.illumination

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

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:

Read current Lux value from the attached OPT3001 sensor.

{
  "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

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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	Used to control the Notecard's IO behavior, including USB port, LED, I2C master, NTN fallback. 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". "+fallback": Setting "+fallback" while Notecard is paired with a Starnote device forces fallback mode: Wi-Fi and cellular are automatically failed over, and all traffic goes through NTN. This state persists across reboots and therefore is discouraged for use in production deployments because it can incur unexpectedly high satellite data costs. "-fallback": Resets "+fallback" to its default state, ensuring fallback mode is only enabled if cellular/Wi-Fi are not available.	-

Examples:

Change the Notecard's I2C address from its default of 0x17 to 0x18.

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

Keep the onboard LED on while the Notecard is awake.

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

Disable the Notecard from acting as an I2C master. Re-enable by using "i2c-master-enable".

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

Force the Notecard to enter fallback mode (cellular/Wi-Fi automatically failed over to NTN).

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

Response

Response schema for card.io request.

No specific parameters defined.

card.led

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Used along with the card.aux API to turn connected LEDs on/off or to manage a single connected NeoPixel.

If using monochromatic LEDs, they must be wired according to the instructions provided in the guide on Using Monitor Mode. Please note that the use of monochromatic LEDs is not supported by Notecard for LoRa.

If using NeoPixels, the NeoPixel (or strip of NeoPixels) must be wired according to the instructions provided in the guide on Using Neo-Monitor Mode.

Parameters:

Parameter	Type	Description	Default
mode	string	Used to specify the color of the LED to turn on or off. Note: Notecard LoRa does not support monochromatic LED modes, only NeoPixels. Allowed Values: "red": Supports LED & NeoPixel "green": Supports LED & NeoPixel "yellow": Supports LED & NeoPixel "blue": Supports NeoPixel "cyan": Supports NeoPixel "magenta": Supports NeoPixel "orange": Supports NeoPixel "white": Supports NeoPixel "gray": Supports NeoPixel	-
off	boolean	Set to true to turn the specified LED or NeoPixel off.	-
on	boolean	Set to true to turn the specified LED or NeoPixel on.	-

Examples:

As shown above, the Notecard must also be in led mode and the LED(s) wired according to the instructions provided in the guide on Using Monitor Mode.

[
  {
    "req": "card.aux",
    "mode": "led"
  },
  {
    "req": "card.led",
    "mode": "red",
    "on": true
  }
]

As shown above, the Notecard must also be in neo, neo-monitor, or track-neo-monitor mode and the NeoPixel(s) wired according to the instructions provided in the guide on Using Neo-Monitor Mode.

[
  {
    "req": "card.aux",
    "mode": "neo"
  },
  {
    "req": "card.led",
    "mode": "blue",
    "on": true
  }
]

Response

Response schema for card.led request.

No specific parameters defined.

card.location

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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.

This request will return the cell tower location or triangulated location of the most recent session if a GPS/GNSS location is not available.

On Notecard LoRa this request can only return a location set through the card.location.mode request's "fixed" mode.

Examples:

Retrieve the last known location of the Notecard.

{
  "req": "card.location"
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
count	integer	The number of consecutive recorded GPS/GNSS failures.	-
dop	number	The "Dilution of Precision" value from the latest GPS/GNSS reading. The lower the value, the higher the confidence level of the reading. Values can be interpreted in this Wikipedia table.	-
lat	number	The latitude in degrees of the last known location.	-
lon	number	The longitude in degrees of the last known location.	-
max	integer	If a geofence is enabled by card.location.mode, meters from the geofence center.	-
mode	string	The GPS/GNSS connection mode. Will be continuous, periodic, or off.. Allowed values: continuous, periodic, off	-
status	string	The current status of the Notecard GPS/GNSS connection.	-
time	integer	UNIX Epoch time. The time of location capture.	-

Examples:

Example response with GPS location data.

{
  "status": "GPS updated (58 sec, 41dB SNR, 9 sats) {gps-active} {gps-signal} {gps-sats} {gps}",
  "mode": "periodic",
  "lat": 42.5776,
  "lon": -70.87134,
  "time": 1598554399,
  "max": 25
}

card.location.mode

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
delete	boolean	Set to true to delete the last known location stored in the Notecard.	-
lat	number	When in periodic or continuous mode, providing this value enables geofencing. The value you provide for this argument should be the latitude of the center of the geofence, in degrees. When in fixed mode, the value you provide for this argument should be the latitude location of the device itself, in degrees.	last known latitude
lon	number	When in periodic or continuous mode, providing this value enables geofencing. The value you provide for this argument should be the longitude of the center of the geofence, in degrees. When in fixed mode, the value you provide for this argument should be the longitude location of the device itself, in degrees.	last known longitude
max	integer	Meters from a geofence center. Used to enable geofence location tracking.	-
minutes	integer	When geofence is enabled, the number of minutes the device should be outside the geofence before the Notecard location is tracked.	5
mode	string	Sets the location mode. Allowed Values: "": Retrieves the current mode. "off": Turns location mode off. Approximate location may still be ascertained from Notehub. "periodic": Samples location at a specified interval, if the device has moved. "continuous": Enables the Notecard's GPS/GNSS module for continuous sampling. When in continuous mode the Notecard samples a new GPS/GNSS reading for every new Note. "fixed": Reports the location as a fixed location using the specified lat and lon coordinates. This is the only supported mode on Notecard LoRa.	-
seconds	integer	When in periodic mode, location will be sampled at this interval, if the Notecard detects motion. If seconds is < 300, during periods of sustained movement the Notecard will leave its onboard GPS/GNSS on continuously to avoid powering the module on and off repeatedly.	-
threshold	integer	When in periodic mode, the number of motion events (registered by the built-in accelerometer) required to trigger GPS to turn on.	0
vseconds	string	In periodic mode, overrides seconds with a voltage-variable value.	-

Examples:

Enable continuous GPS/GNSS sampling.

{
  "req": "card.location.mode",
  "mode": "continuous"
}

Enable periodic location sampling at 1-hour intervals.

{
  "req": "card.location.mode",
  "mode": "periodic",
  "seconds": 3600
}

Enable geofencing with specific location and radius.

{
  "req": "card.location.mode",
  "mode": "periodic",
  "lat": 42.5776,
  "lon": -70.87134,
  "max": 100,
  "minutes": 2
}

Set a fixed location for the device.

{
  "req": "card.location.mode",
  "mode": "fixed",
  "lat": 42.5776,
  "lon": -70.87134
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
lat	number	If geofence is enabled, the geofence center latitude in degrees.	-
lon	number	If geofence is enabled, the geofence center longitude in degrees.	-
max	integer	If geofence is enabled, the meters from geofence center.	-
minutes	integer	If geofence is enabled, the currently configured geofence debounce period.	-
mode	string	The current location mode.. Allowed values: continuous, periodic, off, fixed	-
seconds	integer	If specified, the periodic sample interval.	-
threshold	integer	When in periodic mode, the number of motion events (registered by the built-in accelerometer) required to trigger GPS to turn on.	-
vseconds	string	If specified, the voltage-variable period.	-

Examples:

Example response showing current location mode configuration.

{
  "mode": "continuous",
  "max": 100,
  "lat": 42.5776,
  "lon": -70.87134,
  "minutes": 2,
  "threshold": 4
}

card.location.track

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

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

This request is only available when the card.location.mode request has been set to periodic—e.g. {"req":"card.location.mode","mode":"periodic","seconds":300}. If you want to track and transmit data simultaneously consider using an external GPS/GNSS module with the Notecard.

If you connect a BME280 sensor on the I2C bus, Notecard will include a temperature, humidity, and pressure reading with each captured Note. If you connect an ENS210 sensor on the I2C bus, Notecard will include a temperature and pressure reading with each captured Note. Learn more in _track.qo.

Parameters:

Parameter	Type	Description	Default
file	string	The Notefile in which to store tracked location data. See the _track.qo Notefile's documentation for details on the format of the data captured.	_track.qo
heartbeat	boolean	When start is true, set to true to enable tracking even when motion is not detected. If using heartbeat, also set the hours below.	-
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.	-
payload	string	A base64-encoded binary payload to be included in the next _track.qo Note. See the guide on Sampling at Predefined Intervals for more details.	-
start	boolean	Set to true to start Notefile tracking.	-
stop	boolean	Set to true to stop Notefile tracking.	-
sync	boolean	Set to true to perform an immediate sync to the Notehub each time a new Note is added.	-

Examples:

Start location tracking.

{
  "req": "card.location.track",
  "start": true
}

Stop location tracking.

{
  "req": "card.location.track",
  "stop": true
}

Start tracking with heartbeat mode and immediate sync.

{
  "req": "card.location.track",
  "start": true,
  "sync": true,
  "heartbeat": true,
  "hours": 2
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
file	string	The tracking Notefile, if provided.	-
heartbeat	boolean	true if heartbeat is enabled.	-
minutes	integer	The heartbeat interval in minutes, if provided.	-
seconds	integer	If tracking is enabled and a heartbeat hours value is not set, the tracking interval set in card.location.mode.	-
start	boolean	true if tracking is enabled.	-
stop	boolean	true if tracking is disabled.	-

Examples:

Example response showing tracking configuration with heartbeat enabled.

{
  "start": true,
  "heartbeat": true,
  "file": "locations.qo",
  "minutes": 120
}

card.monitor

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

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
count	integer	The number of pulses to send to the overridden AUX pin LED. Set this value to 0 to return the LED to its default behavior.	-
mode	string	Can be set to one of green, red or yellow to temporarily override the behavior of an AUX pin LED. See Using Monitor Mode for additional details.. Allowed values: green, red, yellow	-
usb	boolean	Set to true to configure LED behavior so that it is only active when the Notecard is connected to USB power.	False

Examples:

Configure the green LED to pulse 5 times.

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

Response

No description available.

No specific parameters defined.

card.motion

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

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. For instance, 5 will sample motion events for the previous five minutes and return a movements string with motion counts in each bucket.	-

Examples:

Request motion information with 2-minute sampling buckets.

{
  "req": "card.motion",
  "minutes": 2
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
alert	boolean	true if the Notecard's accelerometer detected a free-fall since the last request to card.motion.	-
count	integer	The number of accelerometer motion events since the card.motion request was last made.	-
mode	string	Returns the current motion status of the Notecard (e.g. "stopped" or "moving"). Learn how to configure this feature in this guide.	-
motion	integer	Time of the last accelerometer motion event.	-
movements	string	If the minutes argument is provided, a string of base-36 characters, where each character represents the number of accelerometer movements in each bucket during the sample duration. Each character will be a digit 0-9, A-Z to indicate a count of 10-35, or * to indicate a count greater than 35.	-
seconds	integer	If the minutes argument is provided, the duration of each bucket of sample accelerometer movements.	-
status	string	Comma-separated list of accelerometer orientation events that ocurred since the last request to card.motion. One or more of the following: "face-up", "face-down", "portrait-up", "portrait-down", "landscape-right", "landscape-left", "angled".	-

Examples:

Example response showing motion data with sampling buckets.

{
  "count": 17,
  "status": "face-up",
  "alert": true,
  "motion": 1599741952,
  "seconds": 5,
  "movements": "520000000000000000000A"
}

card.motion.mode

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
motion	integer	If motion is > 0, a card.motion request will return a "mode" of "moving" or "stopped". The motion value is the threshold for how many motion events in a single bucket will trigger a motion status change. Learn how to configure this feature in this guide.	-
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. The default sample rate of 1.6Hz could miss short-duration accelerations (e.g. bumps and jolts), and free fall detection may not work reliably with short falls. The penalty for increasing the sample rate to 25Hz is increased current consumption by ~1.5uA relative to the default -1 setting. Allowed Values: -1: 1.6Hz, +/-2G range, 1 milli-G sensitivity 0: Not specified. Do not modify the current sample rate. 1: 25Hz, +/- 16G range, 7.8 milli-G sensitivity 2: 25Hz, +/- 8G range, 3.9 milli-G sensitivity 3: 25Hz, +/- 4G range, 1.95 milli-G sensitivity 4: 25Hz, +/- 2G range, 1 milli-G sensitivity 5: 25Hz, +/- 2G range, 0.25 milli-G sensitivity	-1
start	boolean	true to enable the Notecard accelerometer and start motion tracking.	-
stop	boolean	true to disable the Notecard accelerometer and stop motion tracking.	-

Examples:

Enable motion tracking with default settings.

{
  "req": "card.motion.mode",
  "start": true
}

Enable motion tracking with custom sensitivity and bucket duration.

{
  "req": "card.motion.mode",
  "start": true,
  "seconds": 10,
  "sensitivity": 2
}

Disable motion tracking.

{
  "req": "card.motion.mode",
  "stop": true
}

Set motion threshold for status change detection.

{
  "req": "card.motion.mode",
  "motion": 5,
  "seconds": 60
}

Response

Response from configuring accelerometer motion monitoring parameters.

No specific parameters defined.

card.motion.sync

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Configures automatic sync triggered by Notecard movement.

Parameters:

Parameter	Type	Description	Default
count	integer	The number of most recent motion buckets to examine.	-
minutes	integer	The maximum frequency at which sync will be triggered. Even if a threshold is set and exceeded, there will only be a single sync for this amount of time.	-
start	boolean	true to start motion-triggered syncing.	-
stop	boolean	true to stop motion-triggered syncing.	-
threshold	integer	The number of buckets that must indicate motion in order to trigger a sync. If set to 0, the Notecard will only perform a sync when its orientation changes.	-

Examples:

Enable motion-triggered syncing with default settings.

{
  "req": "card.motion.sync",
  "start": true
}

Set motion sync with specific timing and threshold parameters.

{
  "req": "card.motion.sync",
  "start": true,
  "minutes": 20,
  "count": 20,
  "threshold": 5
}

Disable motion-triggered syncing.

{
  "req": "card.motion.sync",
  "stop": true
}

Configure sync to trigger only on orientation changes.

{
  "req": "card.motion.sync",
  "start": true,
  "threshold": 0,
  "minutes": 10
}

Response

Response from configuring automatic sync triggered by Notecard movement.

No specific parameters defined.

card.motion.track

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Configures automatic capture of Notecard accelerometer motion in a Notefile.

Parameters:

Parameter	Type	Description	Default
count	integer	The number of most recent motion buckets to examine.	-
file	string	The Notefile to use for motion capture Notes. See the _motion.qo Notefile's documentation for details on the format of the data captured.	_motion.qo
minutes	integer	The maximum period to capture Notes in the Notefile.	-
now	boolean	Set to true to trigger the immediate creation of a _motion.qo event if the orientation of the Notecard changes (overriding the minutes setting).	-
start	boolean	true to start motion capture.	-
stop	boolean	true to stop motion capture.	-
threshold	integer	The number of buckets that must indicate motion in order to capture.	-

Examples:

Enable motion tracking with default settings.

{
  "req": "card.motion.track",
  "start": true
}

Set motion tracking with custom parameters and Notefile.

{
  "req": "card.motion.track",
  "start": true,
  "minutes": 20,
  "count": 20,
  "threshold": 5,
  "file": "movements.qo"
}

Disable motion tracking.

{
  "req": "card.motion.track",
  "stop": true
}

Configure motion tracking with immediate orientation change capture.

{
  "req": "card.motion.track",
  "start": true,
  "now": true,
  "minutes": 15
}

Response

Response from configuring automatic capture of Notecard accelerometer motion in a Notefile.

No specific parameters defined.

card.power

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

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:

Request current power consumption data.

{
  "req": "card.power"
}

Configure how often power consumption is logged.

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

Reset power consumption counters back to 0.

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

Response

Response containing power consumption readings and environmental data from the Notecard.

Parameters:

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

Examples:

Example response with power consumption data.

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

card.random

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
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.	-
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.	-

Examples:

Request a random integer between 0 and count-1.

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

Request random bytes returned as base64-encoded payload.

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

Response

Response containing random number or random data generated by the Notecard's hardware random number generator.

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 with a random integer.

{
  "count": 86
}

Example response with base64-encoded random data.

{
  "payload": "SGVsbG8gV29ybGQ="
}

card.restart

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Performs a firmware restart of the Notecard.

Examples:

Perform a firmware restart of the Notecard.

{
  "cmd": "card.restart"
}

Response

Response from the Notecard restart command. The response is typically empty as the restart occurs immediately.

No specific parameters defined.

card.restore

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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.	-

Examples:

Reset Notecard configuration and deprovision from Notehub.

{
  "req": "card.restore",
  "delete": true,
  "connected": true
}

Reset only the file system, forcing re-sync from Notehub.

{
  "req": "card.restore"
}

Response

Response from the Notecard factory reset command. The response is typically empty as the reset and restart occur immediately.

No specific parameters defined.

card.sleep

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

WIFI

Request

Allows the ESP32-based Notecard WiFi v2 to fall back to a low current draw when idle (this behavior differs from the STM32-based Notecards that have a STOP mode where UART and I2C may still operate). Note that this power state is not available if the Notecard is plugged in via USB.

Read more in the guide on using Deep Sleep Mode on Notecard WiFi v2.

Parameters:

Parameter	Type	Description	Default
mode	string	Set to "accel" to wake from deep sleep on any movement detected by the onboard accelerometer. Set to "-accel" to reset to the default setting. Allowed Values: "accel": Wake from deep sleep on any movement detected by the onboard accelerometer. "-accel": Reset to the default setting.	-
off	boolean	Set to true to disable the sleep mode on Notecard.	-
on	boolean	Set to true to enable Notecard to sleep once it is idle for >= 30 seconds.	-
seconds	integer	The number of seconds the Notecard will wait before entering sleep mode (minimum value is 30).	-

Examples:

Enable sleep mode with default settings.

{
  "req": "card.sleep",
  "on": true
}

Enable sleep mode with accelerometer wake functionality.

{
  "req": "card.sleep",
  "on": true,
  "mode": "accel"
}

Set custom wait time before entering sleep mode.

{
  "req": "card.sleep",
  "seconds": 60
}

Disable sleep mode functionality.

{
  "cmd": "card.sleep",
  "off": true
}

Response

Response containing current sleep mode configuration for Notecard WiFi v2.

Parameters:

Parameter	Type	Description	Default
mode	string	Returns "accel" if the Notecard is configured to wake from deep sleep on any movement detected by the onboard accelerometer.	-
off	boolean	true if sleep mode is disabled.	-
on	boolean	true if sleep mode is enabled.	-
seconds	integer	The number of seconds the Notecard will wait before entering sleep mode (only included if default settings are overridden).	-

Examples:

Example response showing current sleep configuration.

{
  "seconds": 10,
  "mode": "accel",
  "on": true
}

card.status

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Returns general information about the Notecard's operating status.

Examples:

Request general information about the Notecard's operating status.

{
  "req": "card.status"
}

Response

Response containing general information about the Notecard's operating status.

Parameters:

Parameter	Type	Description	Default
cell	boolean	true if the modem is currently powered on.	-
connected	boolean	true if connected to Notehub.	-
gps	boolean	true if Notecard's GPS module is currently powered on.	-
inbound	integer	The effective inbound synchronization period being used by the device. See Configuring Synchronization Modes for details on how Notecard synchronization modes work.	-
outbound	integer	The effective outbound synchronization period being used by the device. See Configuring Synchronization Modes for details on how Notecard synchronization modes work.	-
status	string	General status information.	-
storage	integer	The percentage of storage in use on the Notecard.	-
sync	boolean	true if the Notecard has ever connected to Notehub.	-
time	integer	The UNIX Epoch Time of approximately when the Notecard was first powered up.	-
usb	boolean	true if the Notecard is being powered by USB.	-
wifi	boolean	true if the Notecard's Wi-Fi radio is currently powered on.	-

Examples:

Example response showing Notecard operating status information.

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

card.temp

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

When using a Notecard Cellular or Notecard Cell+WiFi, if you connect a BME280 sensor on the I2C bus the Notecard will add temperature, pressure, and humidity fields to the response. If you connect an ENS210 sensor on the I2C bus the Notecard will add temperature and pressure fields to the response.

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. When using card.aux track mode, the sensor temperature, pressure, and humidity is also included with each Note.	-
status	string	Overrides minutes with a voltage-variable value. For example: "usb:15;high:30;normal:60;720". See Voltage-Variable Sync Behavior for more information on configuring these values.	-
stop	boolean	If set to true, the Notecard will stop logging the temperature value at the interval specified with the minutes parameter (see above).	-
sync	boolean	If set to true, the Notecard will immediately sync any pending _temp.qo Notes created with the minutes parameter (see above).	-

Examples:

Get current temperature from Notecard's onboard sensor.

{
  "req": "card.temp"
}

Set up automatic temperature logging at 30-minute intervals.

{
  "req": "card.temp",
  "minutes": 30
}

Stop automatic temperature logging.

{
  "cmd": "card.temp",
  "stop": true
}

Immediately sync pending temperature notes.

{
  "cmd": "card.temp",
  "sync": true
}

Response

Response containing temperature readings from the Notecard's onboard sensor and any connected I2C sensors.

Parameters:

Parameter	Type	Description	Default
calibration	number	The calibration differential of the Notecard's onboard sensor.	-
humidity	number	If the Notecard finds a BME280 sensor on the I2C bus, this field will be set to the humidity percentage value from the connected sensor.	-
pressure	number	If the Notecard finds a BME280 or ENS210 sensor on the I2C bus, this field will be set to the atmospheric pressure value from the connected sensor in Pascals.	-
temperature	number	If the Notecard finds a BME280 or ENS210 sensor on the I2C bus, this field will be set to the temperature value from the connected sensor in degrees centigrade.	-
usb	boolean	true if the Notecard is connected to USB power.	-
value	number	The current temperature from the Notecard's onboard sensor in degrees centigrade, including the calibration offset.	-
voltage	number	The current voltage.	-

Examples:

Example response with onboard sensor temperature and calibration.

{
  "value": 27.625,
  "calibration": -3.0
}

Example response with BME280 sensor data and power information.

{
  "value": 25.5,
  "calibration": -2.5,
  "temperature": 24.8,
  "humidity": 45.2,
  "pressure": 101325,
  "usb": true,
  "voltage": 4.95
}

card.time

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Retrieves current date and time information in UTC. 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:

Retrieve current date and time information in UTC with location data if available.

{
  "req": "card.time"
}

Response

Response containing current date and time information in UTC along with location data if available.

Parameters:

Parameter	Type	Description	Default
area	string	The geographic area of the Notecard, if the cell tower is recognized.	-
country	string	The country where the Notecard is located, 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.	-
minutes	integer	Number of minutes East of GMT, if the cell tower is recognized.	-
time	integer	The current time in UTC. Will only populate if the Notecard has completed a sync to Notehub to obtain the time.	-
zone	string	The time zone of the Notecard, if the cell tower is recognized.	-

Examples:

Example response with full time and location information.

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

Example response when time is available but location data hasn't been obtained yet.

{
  "zone": "UTC,Unknown"
}

card.trace

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Enable and disable trace mode on a Notecard for debugging.

Parameters:

Parameter	Type	Description	Default
mode	string	Set to "on" to enable trace mode on a Notecard, or "off" to disable it.. Allowed values: on, off	-

Examples:

Enable trace mode for debugging the Notecard.

{
  "req": "card.trace",
  "mode": "on"
}

Disable trace mode on the Notecard.

{
  "cmd": "card.trace",
  "mode": "off"
}

Response

Response from trace mode configuration request. Returns an empty object upon successful completion.

No specific parameters defined.

card.transport

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

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
allow	boolean	Set to true to allow adding Notes to non-compact Notefiles while connected over a non-terrestrial network. See Define NTN vs non-NTN Templates.	False
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" ⚠️ DEPRECATED (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
umin	boolean	Set to true to force a longer network transport timeout when using Wideband Notecards.	False

Examples:

Configure Notecard Cell+WiFi to prioritize WiFi while falling back to cellular.

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

Configure device to use WiFi connectivity only.

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

Configure device to use cellular connectivity only.

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

Reset the transport mode to device default settings.

{
  "cmd": "card.transport",
  "method": "-"
}

Enable NTN (Non-Terrestrial Network) mode for Starnote connectivity.

{
  "req": "card.transport",
  "method": "ntn"
}

Configure triple fallback: WiFi → cellular → NTN with custom timeout.

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

Response

Response containing the current connectivity method configuration of the Notecard.

Parameters:

Parameter	Type	Description	Default
method	string	The connectivity method currently enabled on the device.. Allowed values: -, cell, cell-ntn, dual-wifi-cell, ntn, wifi, wifi-cell, wifi-cell-ntn, wifi-ntn	-

Examples:

Response showing WiFi-cellular priority transport mode is active.

{
  "method": "wifi-cell"
}

Response showing cellular-only transport mode is active.

{
  "method": "cell"
}

Response showing NTN (Non-Terrestrial Network) transport mode is active.

{
  "method": "ntn"
}

card.triangulate

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Enables or disables a behavior by which the Notecard gathers information about surrounding cell towers and/or Wi-Fi access points with each new Notehub session.

Parameters:

Parameter	Type	Description	Default
minutes	integer	Minimum delay, in minutes, between triangulation attempts. Use 0 for no time-based suppression.	0
mode	string	The triangulation approach to use for determining the Notecard location. The following keywords can be used separately or together in a comma-delimited list, in any order. See Using Cell Tower & Wi-Fi Triangulation for more information. Allowed Values: "cell": Enables cell tower scanning to determine the position of the Device. "wifi": Enables the use of nearby Wi-Fi access points to determine the position of the Device. To leverage this feature, the host will need to provide access point information to the Notecard via the text argument in subsequent requests. "-": Clear the currently-set triangulation mode.	-
on	boolean	true to instruct the Notecard to triangulate even if the module has not moved. Only takes effect when set is true.	False
set	boolean	true to instruct the module to use the state of the on and usb arguments.	False
text	string	When using Wi-Fi triangulation, a newline-terminated list of Wi-Fi access points obtained by the external module. Format should follow the ESP32's AT+CWLAP command output.	-
time	integer	When passed with text, records the time that the Wi-Fi access point scan was performed. If not provided, Notecard time is used.	-
usb	boolean	true to use perform triangulation only when the Notecard is connected to USB power. Only takes effect when set is true.	False

Examples:

Enable triangulation using cell towers only.

{
  "req": "card.triangulate",
  "mode": "cell",
  "on": true,
  "set": true
}

Enable triangulation using both Wi-Fi and cell towers when connected to USB power.

{
  "req": "card.triangulate",
  "mode": "wifi,cell",
  "on": true,
  "usb": true,
  "set": true
}

Send a newline-terminated list of Wi-Fi access points to the Notecard for triangulation.

{
  "req": "card.triangulate",
  "text": "+CWLAP:(4,\"Blues\",-51,\"74:ac:b9:12:12:f8\",1)\n+CWLAP:(3,\"AAAA-62DD\",-70,\"6c:55:e8:91:62:e1\",11)\n+CWLAP:(4,\"Blues\",-81,\"74:ac:b9:11:12:23\",1)\n+CWLAP:(4,\"Blues\",-82,\"74:ac:a9:12:19:48\",11)\n+CWLAP:(4,\"Free Parking\",-83,\"02:18:4a:11:60:31\",6)\n+CWLAP:(5,\"GO\",-84,\"01:13:6a:13:90:30\",6)\n+CWLAP:(4,\"AAAA-5C62-2.4\",-85,\"d8:97:ba:7b:fd:60\",1)\n+CWLAP:(3,\"DIRECT-a5-HP MLP50\",-86,\"fa:da:0c:1b:16:a5\",6)\n+CWLAP:(3,\"DIRECT-c6-HP M182 LaserJet\",-88,\"da:12:65:44:31:c6\",6)\n\n"
}

Disable triangulation mode.

{
  "req": "card.triangulate",
  "mode": "-"
}

Response

Response containing triangulated location information and triangulation settings.

Parameters:

Parameter	Type	Description	Default
length	integer	The length of the text buffer provided in the current or a previous request.	-
mode	string	A comma-separated list indicating the active triangulation modes.	-
motion	integer	Time of last detected Notecard movement.	-
on	boolean	true if triangulation scans will be performed even if the device has not moved.	-
time	integer	Time of last triangulation scan.	-
usb	boolean	true if triangulation scans will be performed only when the device is USB-powered.	-

Examples:

Response showing full triangulation configuration and status information.

{
  "usb": true,
  "mode": "wifi,cell",
  "length": 443,
  "on": true,
  "time": 1606755042,
  "motion": 1606757487
}

Response showing basic triangulation mode configuration.

{
  "mode": "cell",
  "on": false
}

card.usage.get

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Returns the card's network usage statistics.

Parameters:

Parameter	Type	Description	Default
mode	string	The time period to use for statistics. Must be one of: Allowed Values: "total": All stats since the Notecard was activated. "1hour": Statistics for the last hour period. "1day": Statistics for the last day period. "30day": Statistics for the last 30 days period.	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:

Retrieve all usage statistics since Notecard activation.

{
  "req": "card.usage.get"
}

Get usage statistics for a specific day, 5 days ago.

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

Get usage statistics for the current hour period.

{
  "req": "card.usage.get",
  "mode": "1hour"
}

Get usage statistics for the last 30 days.

{
  "req": "card.usage.get",
  "mode": "30day"
}

Response

Response containing network usage statistics for the specified time period.

Parameters:

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

Examples:

Example response showing comprehensive network usage data.

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

Example response with basic usage metrics.

{
  "seconds": 3600,
  "time": 1700000000,
  "bytes_sent": 1024,
  "bytes_received": 2048
}

card.usage.test

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Calculates a projection of how long the available data quota will last based on the observed usage patterns.

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:

Calculate data quota projection based on the last 7 days with 500MB quota.

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

Calculate data quota projection based on the last 12 hours.

{
  "req": "card.usage.test",
  "hours": 12
}

Test with default 1024MB quota using 30 days of data.

{
  "req": "card.usage.test",
  "days": 30
}

Response

Response containing data usage projection and analysis results.

Parameters:

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

Examples:

Example response showing comprehensive usage projection data.

{
  "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
}

Example response with essential projection metrics.

{
  "max": 1825,
  "days": 30,
  "bytes_per_day": 56832,
  "seconds": 2592000,
  "time": 1700000000
}

card.version

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Returns firmware version information for the Notecard.

Parameters:

Parameter	Type	Description	Default
api	integer	Specify a major version of the Notecard firmware that a host expects to use.	-

Examples:

Retrieve firmware version and device information.

{
  "req": "card.version"
}

Response

Response containing firmware version information and device details.

Parameters:

Parameter	Type	Description	Default
api	integer	The current Notecard API major version in use.	-
board	string	The Notecard board version number.	-
body	object	An object containing Notecard firmware details for programmatic access.	-
cell	boolean	If true, indicates the Notecard supports cellular connectivity.	-
device	string	The DeviceUID of the Notecard.	-
gps	boolean	If true, indicates the Notecard has an onboard GPS module.	-
name	string	The official name of the device.	-
sku	string	The Notecard SKU.	-
version	string	The full version number of the Notecard firmware.	-
wifi	boolean	If true, indicates the Notecard supports Wi-Fi connectivity.	-

Examples:

Example response showing comprehensive version and device information.

{
  "version": "notecard-5.3.1",
  "device": "dev:000000000000000",
  "name": "Blues Wireless Notecard",
  "sku": "NOTE-NBGL",
  "board": "1.11",
  "cell": true,
  "gps": true,
  "api": 5,
  "body": {
    "org": "Blues Wireless",
    "product": "Notecard",
    "target": "r5",
    "version": "notecard-5.3.1",
    "ver_major": 5,
    "ver_minor": 3,
    "ver_patch": 1,
    "ver_build": 371,
    "built": "Sep  5 2023 12:21:30"
  }
}

card.voltage

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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
alert	boolean	When enabled and the usb argument is set to true, the Notecard will add an entry to the health.qo Notefile when USB power is connected or disconnected.	False
calibration	number	The offset, in volts, to account for the forward voltage drop of the diode used between the battery and Notecard in either Blues- or customer-designed Notecarriers.	0.35
hours	integer	The number of hours to analyze, up to 720 (30 days).	720
mode	string	Used to set voltage thresholds based on how the Notecard will be powered, and which can be used to configure voltage-variable Notecard behavior. Each value is shorthand that assigns a battery voltage reading to a given device state like high, normal, low, and dead. NOTE: Setting voltage thresholds is not supported on the Notecard XP. Allowed Values: "default": Default behavior. Equivalent to normal:2.5;dead:0. "lipo": LiPo batteries. Equivalent to usb:4.6;high:4.0;normal:3.5;low:3.2;dead:0. "l91": L91 batteries. Equivalent to high:5.0;normal:4.5;low:0. "alkaline": Alkaline batteries. Equivalent to usb:4.6;high:4.2;normal:3.6;low:0. "tad": Tadiran HLC batteries. Equivalent to usb:4.6;normal:3.2;low:0. "lic": Lithium-ion capacitors. Equivalent to usb:4.6;high:3.8;normal:3.1;low:0. "?": Query the Notecard for its currently-set thresholds.	default
name	string	Specifies an environment variable to override application default timing values.	-
offset	integer	Number of hours to move into the past before starting analysis.	0
set	boolean	Used along with calibration, set to true to specify a new calibration value.	False
sync	boolean	When enabled and the usb argument is set to true, the Notecard will perform a sync when USB power is connected or disconnected.	False
usb	boolean	When enabled, the Notecard will monitor for changes to USB power state.	False
vmax	number	Ignore voltage readings above this level when performing calculations.	4.5
vmin	number	Ignore voltage readings below this level when performing calculations.	2.5

Examples:

Retrieve voltage information with trend analysis for 300 hours.

{
  "req": "card.voltage",
  "hours": 300,
  "vmax": 4,
  "vmin": 2.2
}

Configure voltage thresholds for LiPo battery operation.

{
  "req": "card.voltage",
  "mode": "lipo"
}

Query the Notecard for its currently-set voltage thresholds.

{
  "req": "card.voltage",
  "mode": "?"
}

Enable USB power state monitoring with alerts and sync.

{
  "req": "card.voltage",
  "usb": true,
  "alert": true,
  "sync": true
}

Response

Response containing current voltage information and historical trend analysis.

Parameters:

Parameter	Type	Description	Default
daily	number	Change of moving average in the last 24 hours, if relevant to the time period analyzed.	-
hours	integer	The number of hours used for trend analysis.	-
minutes	integer	Represents the Notecard's uptime in minutes. This field is not present when the device is powered via USB.	-
mode	string	The current voltage-variable threshold value returned from Notecard. For example, if the voltage threshold is "usb:4.6;normal:3.5;dead:0" and the power source returns a voltage of 3.9, the mode value would be "normal".	-
monthly	number	Change of moving average in the last 30 days, if relevant to the time period analyzed.	-
usb	boolean	true if the Notecard is connected to USB power.	-
value	number	The current voltage.	-
vavg	number	The average voltage value during the measured period.	-
vmax	number	The highest voltage value captured during the measurement period.	-
vmin	number	The lowest voltage value captured during the measurement period.	-
weekly	number	Change of moving average in the last 7 days, if relevant to the time period analyzed.	-

Examples:

Example response when Notecard is powered via USB.

{
  "usb": true,
  "hours": 120,
  "mode": "usb",
  "value": 5.112190219747135,
  "vmin": 4,
  "vmax": 4,
  "vavg": 4
}

Example response showing battery voltage with trend analysis.

{
  "mode": "normal",
  "usb": false,
  "value": 3.85,
  "hours": 720,
  "vmin": 3.2,
  "vmax": 4.1,
  "vavg": 3.75,
  "daily": -0.05,
  "weekly": -0.3,
  "monthly": -0.8,
  "minutes": 43200
}

card.wifi

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL+WIFI WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
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.	-
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.	-
ssid	string	The SSID of the Wi-Fi access point. Alternatively, use - to clear an already set SSID.	-
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 to connect to an access point.

{
  "req": "card.wifi",
  "ssid": "<ssid name>",
  "password": "<password>"
}

Clear existing Wi-Fi credentials to disconnect.

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

Configure SoftAP with custom name and organization branding.

{
  "req": "card.wifi",
  "name": "ACME Inc",
  "org": "ACME Inc"
}

Configure SoftAP name with MAC address suffix for unique identification.

{
  "req": "card.wifi",
  "name": "acme-",
  "org": "ACME Inc"
}

Set up multiple Wi-Fi access points for fallback connectivity.

{
  "req": "card.wifi",
  "text": "[\"FIRST-SSID\",\"FIRST-PASSWORD\"],[\"SECOND-SSID\",\"SECOND-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.	-
security	string	The security protocol the Wi-Fi access point uses.	-
ssid	string	The SSID of the Wi-Fi access point.	-
version	string	The Silicon Labs WF200 Wi-Fi Transceiver binary version.	-

Examples:

Example response showing comprehensive Wi-Fi connection information.

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

Example response with basic Wi-Fi access point information.

{
  "ssid": "HomeNetwork",
  "security": "wpa3"
}

Example response showing Wi-Fi transceiver version.

{
  "version": "3.12.3"
}

card.wireless

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

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
apn	string	Access Point Name (APN) when using an external SIM. Use "-" to reset to the Notecard default APN.	-
hours	integer	When using the method argument with "dual-primary-secondary" or "dual-secondary-primary", this is the number of hours after which the Notecard will attempt to switch back to the preferred SIM.	-
method	string	Used when configuring a Notecard to failover to a different SIM. Allowed Values: "-": Resets the Notecard to the default method. "dual-primary-secondary": Will attempt to register with the internal SIM first, then failover to the external SIM. "dual-secondary-primary": Will attempt to register with the external SIM first, then failover to the internal SIM. "primary": Will exclusively use the internal SIM. "secondary": Will exclusively use the external SIM.	-
mode	string	Network scan mode. Must be one of: Allowed Values: "-": Reset to the default mode. "auto": Perform automatic band scan mode (this is the default mode). "m": Restrict the modem to Cat-M1 (applies exclusively to Narrowband Notecard Cellular devices). "nb": Restrict the modem to Cat-NB1 (applies exclusively to Narrowband Notecard Cellular devices). "gprs": Restrict the modem to EGPRS (applies exclusively to Narrowband Notecard Cellular devices).	-

Examples:

Request current network state without any modifications.

{
  "req": "card.wireless"
}

Restrict the modem to Cat-NB1 for narrowband connectivity.

{
  "req": "card.wireless",
  "mode": "nb"
}

Reset network scan mode to default behavior.

{
  "req": "card.wireless",
  "mode": "-"
}

Configure APN for external SIM card usage.

{
  "req": "card.wireless",
  "apn": "myapn.nb"
}

Configure dual SIM failover with external SIM priority.

{
  "req": "card.wireless",
  "apn": "myapn.nb",
  "method": "dual-primary-secondary"
}

Response

Response containing wireless connection status, signal quality information, and detailed modem/network data from the Notecard.

Parameters:

Parameter	Type	Description	Default
count	integer	Number of bars of signal quality.	-
net	object	An object with detailed modem, radio access technology, and signal information (details will differ depending on the type of Notecard).	-
status	string	The current status of the wireless connection and modem.	-

Examples:

Example response showing comprehensive wireless connection and signal information.

{
  "status": "{modem-off}",
  "count": 1,
  "net": {
    "iccid": "00000000000000000000",
    "imsi": "000000000000000",
    "imei": "000000000000000",
    "modem": "EG91NAXGAR07A03M1G_BETA0415_01.001.01.001",
    "band": "LTE BAND 2",
    "rat": "lte",
    "rssir": -69,
    "rssi": -70,
    "rsrp": -105,
    "sinr": -3,
    "rsrq": -17,
    "bars": 1,
    "mcc": 310,
    "mnc": 410,
    "lac": 28681,
    "cid": 211150856,
    "updated": 1599225076
  }
}

Example response with basic signal strength and status.

{
  "status": "connected",
  "count": 3
}

Example response showing detailed network information.

{
  "status": "searching",
  "count": 2,
  "net": {
    "band": "LTE BAND 12",
    "rat": "lte",
    "rssi": -85,
    "bars": 2,
    "mcc": 310,
    "mnc": 260
  }
}

card.wireless.penalty

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

View the current state of a Notecard Penalty Box, manually remove the Notecard from a penalty box, or override penalty box defaults.

Parameters:

Parameter	Type	Description	Default
add	integer	The number of minutes to add to successive retries. Used with the set argument to override the Network Registration Failure Penalty Box defaults.	15
max	integer	The maximum number of minutes that a device can be in a Network Registration Failure Penalty Box. Used with the set argument to override the Network Registration Failure Penalty Box defaults.	4320
min	integer	The number of minutes of the first retry interval of a Network Registration Failure Penalty Box. Used with the set argument to override the Network Registration Failure Penalty Box defaults.	15
rate	number	The rate at which the penalty box time multiplier is increased over successive retries. Used with the set argument to override the Network Registration Failure Penalty Box defaults.	1.25
reset	boolean	Set to true to remove the Notecard from certain types of penalty boxes.	-
set	boolean	Set to true to override the default settings of the Network Registration Failure Penalty Box.	-

Examples:

Request current penalty box status and information.

{
  "req": "card.wireless.penalty"
}

Reset and remove the Notecard from penalty box conditions.

{
  "req": "card.wireless.penalty",
  "reset": true
}

Configure custom penalty box parameters with modified defaults.

{
  "req": "card.wireless.penalty",
  "set": true,
  "rate": 2.0,
  "add": 10,
  "max": 720,
  "min": 5
}

Response

Response containing penalty box status information, including failure counts, duration, and current penalty conditions from the Notecard.

Parameters:

Parameter	Type	Description	Default
count	integer	The number of consecutive network registration failures.	-
minutes	integer	The time since the first network registration failure.	-
seconds	integer	If the Notecard is in a Penalty Box, the number of seconds until the penalty condition ends.	-
status	string	If the Notecard is in a Penalty Box, this field provides the associated Error and Status Codes.	-

Examples:

Example response showing Notecard in penalty box with active network registration failure.

{
  "seconds": 3324,
  "minutes": 69,
  "status": "network: can't connect (55.4 min remaining) {registration-failure}{network}{extended-network-failure}",
  "count": 6
}

Example response when Notecard is not in a penalty box.

{
  "minutes": 0,
  "count": 0
}

Example response with basic penalty metrics without active penalty.

{
  "count": 3,
  "minutes": 15
}

dfu.get

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

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:

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

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

Verify that the Notecard is in DFU mode without retrieving data.

{
  "req": "dfu.get",
  "length": 0
}

Read the first 1024 bytes of firmware data from the beginning.

{
  "req": "dfu.get",
  "length": 1024,
  "offset": 0
}

Response

Response containing base64-encoded firmware data retrieved from the Notecard for use with host MCU firmware updates.

Parameters:

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

Examples:

Example response with base64-encoded firmware data.

{
  "payload": "AAAAAAAAAAAAAAAAcy8ACIEvAAgAAAAAjy8ACJ0vAAg="
}

Example response when verifying DFU mode with length 0.

{
  "payload": ""
}

Example response with a small firmware data block.

{
  "payload": "dGVzdGZpcm13YXJlZGF0YQ=="
}

dfu.status

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
err	string	If err text is provided along with "stop":true, this sets the host DFU to an error state with the specified string.	-
name	string	Determines which type of firmware update status to view. The value can be "user" (default), which gets the status of MCU host firmware updates, or "card", which gets the status of Notecard firmware updates. Allowed Values: "user": Gets the status of MCU host firmware updates (default). "card": Gets the status of Notecard firmware updates.	-
off	boolean	true to disable firmware downloads from Notehub.	-
on	boolean	true to allow firmware downloads from Notehub.	-
status	string	When setting stop to true, an optional string synchronized to Notehub, which can be used for informational or diagnostic purposes.	-
stop	boolean	true to clear DFU state and delete the local firmware image from the Notecard.	-
version	['string', 'object']	Version information on the host firmware to pass to Notehub. You may pass a simple version number string (e.g. "1.0.0.0"), or an object with detailed information about the firmware image (recommended). If you provide an object it must take the following form. {"org":"my-organization","product":"My Product","description":"A description of the image","version":"1.2.4","built":"Jan 01 2025 01:02:03","ver_major":1,"ver_minor":2,"ver_patch":4,"ver_build": 5,"builder":"The Builder"} Code to help you generate a version with the correct formatting is available in Enabling Notecard Outboard Firmware Update.	-
vvalue	string	A voltage-variable string that controls, by Notecard voltage, whether or not DFU is enabled. Use a boolean 1 (on) or 0 (off) for each source/voltage level: usb:<1/0>;high:<1/0>;normal:<1/0>;low:<1/0>;dead:0.	-

Examples:

Enable firmware downloads from Notehub.

{
  "req": "dfu.status",
  "on": true
}

Disable firmware downloads from Notehub.

{
  "req": "dfu.status",
  "off": true
}

Enable DFU downloads only when USB-powered or high voltage.

{
  "req": "dfu.status",
  "vvalue": "usb:1;high:1;normal:0;low:0;dead:0"
}

Get the status of Notecard firmware updates.

{
  "req": "dfu.status",
  "name": "card"
}

Clear DFU state and provide status information.

{
  "req": "dfu.status",
  "stop": true,
  "status": "Update cancelled by user"
}

Provide version information for host firmware.

{
  "req": "dfu.status",
  "version": "1.2.4"
}

Response

Response containing the current DFU mode and status information for firmware downloads.

Parameters:

Parameter	Type	Description	Default
body	object	Object that includes essential details about the firmware binary, including its length, md5 hash, notes from the Notehub admin, created and updated dates, and more.	-
mode	string	The current DFU mode. Will be one of: Allowed Values: "idle": There is no firmware download in progress, and no data previously downloaded. "error": The download or verification has failed. In this mode, the status field will contain the reason. "downloading": The download is in progress. In this mode, the status field will contain info about progress. "ready": The firmware data is fully downloaded. "completed": The firmware has been installed.	-
off	boolean	true when firmware downloads are disabled.	-
on	boolean	true when firmware downloads are enabled.	-
pending	boolean	true when Notecard DFU is currently in-progress.	-
status	string	The current status of the firmware download.	-

Examples:

Example response showing firmware is ready for installation.

{
  "mode": "ready",
  "status": "successfully downloaded",
  "on": true,
  "body": {
    "crc32": 2525287425,
    "created": 1599163431,
    "info": {},
    "length": 42892,
    "md5": "5a3f73a7f1b4bc8917b12b36c2532969",
    "modified": 1599163431,
    "name": "stm32-new-firmware$20200903200351.bin",
    "notes": "Latest prod firmware",
    "source": "stm32-new-firmware.bin",
    "type": "firmware"
  }
}

Example response showing no firmware download in progress.

{
  "mode": "idle",
  "status": "no download in progress",
  "on": true
}

Example response showing firmware download in progress.

{
  "mode": "downloading",
  "status": "downloading: 45% complete",
  "on": true,
  "pending": true
}

Example response showing download error.

{
  "mode": "error",
  "status": "download failed: checksum mismatch",
  "on": true
}

env.default

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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	The name of the environment variable (case-insensitive).	-
text	string	The value of the variable. Pass "" or omit from the request to delete it.	-

Examples:

Set a default value for an environment variable.

{
  "req": "env.default",
  "name": "monitor-pump",
  "text": "on"
}

Clear the default value for an environment variable by omitting text.

{
  "req": "env.default",
  "name": "monitor-pump"
}

Set an environment variable default to an empty string.

{
  "req": "env.default",
  "name": "debug-mode",
  "text": ""
}

Set a default value for a numeric environment variable.

{
  "req": "env.default",
  "name": "sample-rate",
  "text": "60"
}

Response

Empty response confirming successful execution of the environment variable default setting or deletion.

No specific parameters defined.

env.get

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
name	string	The name of the environment variable (case-insensitive). Omit to return all environment variables known to the Notecard.	-
names	array	A list of one or more variables to retrieve, by name (case-insensitive).	-
time	integer	Request a modified environment variable or variables from the Notecard, but only if modified after the time provided.	-

Examples:

Retrieve a specific environment variable by name.

{
  "req": "env.get",
  "name": "monitor-pump-one"
}

Retrieve a variable only if modified after the specified time.

{
  "req": "env.get",
  "name": "monitor-pump-one",
  "time": 1656315835
}

Retrieve multiple environment variables by name.

{
  "req": "env.get",
  "names": [
    "monitor-pump-one",
    "monitor-pump-two"
  ]
}

Retrieve all environment variables known to the Notecard.

{
  "req": "env.get"
}

Response

Response containing environment variable values and metadata based on the request parameters.

Parameters:

Parameter	Type	Description	Default
body	object	If a name was not specified, an object with name and value pairs for all environment variables.	-
text	string	If a name was specified, the value of the environment variable.	-
time	integer	The time of the Notecard variable or variables change.	-

Examples:

Response for a single environment variable request.

{
  "monitor-pump-one": "on",
  "time": 1656315835
}

Response for multiple environment variables request.

{
  "body": {
    "monitor-pump-one": "on",
    "monitor-pump-two": "off"
  },
  "time": 1656315835
}

Response for all environment variables request.

{
  "body": {
    "monitor-pump-one": "on",
    "monitor-pump-two": "off",
    "monitor-pump-three": "on"
  },
  "time": 1656315835
}

env.modified

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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.	-

Examples:

Get the timestamp of the last environment variable change.

{
  "req": "env.modified"
}

Check if environment variables have been modified since a specific time.

{
  "req": "env.modified",
  "time": 1605814400
}

Response

Response containing the timestamp of the last environment variable change.

Parameters:

Parameter	Type	Description	Default
time	integer	Timestamp indicating the last time any environment variable was changed on the device.	-

Examples:

Response containing the last modification timestamp.

{
  "time": 1605814493
}

env.set

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Sets a local environment variable on the Notecard. Local environment variables cannot be overridden by a Notehub variable of any scope.

Parameters:

Parameter	Type	Description	Default
name	string	The name of the environment variable (case-insensitive).	-
text	string	The value of the variable. Pass "" or omit from the request to delete it.	-

Examples:

Set a local environment variable on the Notecard.

{
  "req": "env.set",
  "name": "monitor-pump",
  "text": "on"
}

Clear a local environment variable by omitting text.

{
  "req": "env.set",
  "name": "monitor-pump"
}

Set an environment variable to an empty string.

{
  "req": "env.set",
  "name": "debug-mode",
  "text": ""
}

Response

Response containing the timestamp of the environment variable change.

Parameters:

Parameter	Type	Description	Default
time	integer	The logged time of the variable change.	-

Examples:

Response containing the timestamp of when the variable was set.

{
  "time": 1605814493
}

env.template

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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.

Using templated environment variables also allows the Notecard to optimize the network traffic related to sending and receiving environment variable updates.

Parameters:

Parameter	Type	Description	Default
body	object	A sample JSON body that specifies environment variables names and values as "hints" for the data type. Possible data types are: boolean, integer, float, and string. See Understanding Template Data Types for a full explanation of type hints.	-

Examples:

Provide a schema with data type hints for environment variables.

{
  "req": "env.template",
  "body": {
    "env_var_int": 11,
    "env_var_string": "10"
  }
}

Template with multiple data types including boolean and float.

{
  "req": "env.template",
  "body": {
    "enabled": true,
    "temperature": 23.5,
    "count": 42,
    "name": "sensor"
  }
}

Clear the environment variable template by omitting the body.

{
  "req": "env.template"
}

Response

Response containing the maximum number of bytes for the environment variable template.

Parameters:

Parameter	Type	Description	Default
bytes	integer	The maximum number of bytes that will be used when environment variables are communicated or stored, so long as the variables do not include variable-length strings.	-

Examples:

Response showing the maximum bytes used by the environment variable template.

{
  "bytes": 22
}

file.changes

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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.

Note: This request is a Notefile API request, only. .qo Notes in Notehub are automatically ingested and stored, or sent to applicable Routes.

Parameters:

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

Examples:

Check all Notefiles for changes without specifying files or tracker.

{
  "req": "file.changes"
}

Check specific Notefiles for changes.

{
  "req": "file.changes",
  "files": [
    "sensors.qo",
    "data.qo"
  ]
}

Use a change tracker to monitor file changes over time.

{
  "req": "file.changes",
  "tracker": "my-tracker"
}

Combine change tracker with specific file monitoring.

{
  "req": "file.changes",
  "files": [
    "sensors.qo"
  ],
  "tracker": "sensor-tracker"
}

Response

Response containing information about file changes and their status.

Parameters:

Parameter	Type	Description	Default
changes	integer	If a change tracker is used, the number of changes across all files.	-
info	object	An object with a key for each Notefile that matched the request parameters, and value object with the changes and total for each file.	-
pending	boolean	Set to true if this was a pending changes request and there are changes	-
total	integer	The total of local Notes across all Notefiles. This includes Inbound Notes that have not been deleted, as well as outbound Notes that have yet to sync.	-

Examples:

Response showing changes detected in monitored files.

{
  "changes": 5,
  "total": 5,
  "info": {
    "my-settings.db": {
      "changes": 3,
      "total": 3
    },
    "other-settings.db": {
      "changes": 2,
      "total": 2
    }
  }
}

file.changes.pending

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

Examples:

Query for pending file changes awaiting upload to Notehub.

{
  "req": "file.changes.pending"
}

Response

Response containing information about file changes pending upload to Notehub.

Parameters:

Parameter	Type	Description	Default
changes	integer	The number of changes across all files.	-
info	object	An object with a key for each Notefile and value object with the changes and total for each file.	-
pending	boolean	true if there are pending changes.	-
total	integer	The total of unsynced notes across all Notefiles.	-

Examples:

Response showing pending changes across multiple files.

{
  "total": 3,
  "changes": 3,
  "pending": true,
  "info": {
    "sensors.qo": {
      "changes": 3,
      "total": 3
    }
  }
}

Response when no changes are pending upload.

{
  "total": 0,
  "changes": 0,
  "pending": false
}

Response with pending changes across multiple Notefiles.

{
  "total": 5,
  "changes": 5,
  "pending": true,
  "info": {
    "sensors.qo": {
      "changes": 3,
      "total": 3
    },
    "data.qo": {
      "changes": 2,
      "total": 2
    }
  }
}

file.clear

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Used to clear the contents of a specified outbound (.qo/.qos) Notefile, deleting all pending Notes.

Parameters:

Parameter	Type	Description	Default
file	string	The name of the Notefile whose Notes you wish to delete.	-

Examples:

Clear all pending Notes from an outbound Notefile.

{
  "req": "file.clear",
  "file": "data.qo"
}

Clear all pending Notes from an encrypted outbound Notefile.

{
  "req": "file.clear",
  "file": "sensors.qos"
}

Response

Response confirming the clearing of the specified Notefile.

No specific parameters defined.

file.delete

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Deletes Notefiles and the Notes they contain.

Parameters:

Parameter	Type	Description	Default
files	array	One or more files to delete.	-

Examples:

Delete multiple Notefiles and their contents.

{
  "req": "file.delete",
  "files": [
    "my-settings.db",
    "other-settings.db"
  ]
}

Delete a single Notefile and its contents.

{
  "req": "file.delete",
  "files": [
    "data.qo"
  ]
}

Response

Response confirming the deletion of the specified Notefiles.

No specific parameters defined.

file.stats

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Gets resource statistics about local Notefiles.

Parameters:

Parameter	Type	Description	Default
file	string	Returns the stats for the specified Notefile only.	-

Examples:

Get resource statistics for all Notefiles.

{
  "req": "file.stats"
}

Get resource statistics for a specific Notefile.

{
  "req": "file.stats",
  "file": "sensors.qo"
}

Response

Response containing resource statistics about local Notefiles.

Parameters:

Parameter	Type	Description	Default
changes	integer	The number of Notes across all Notefiles pending sync.	-
sync	boolean	true if a sync is recommended based on the number of pending notes.	-
total	integer	The total number of Notes across all Notefiles.	-

Examples:

Response with resource statistics showing pending sync recommendation.

{
  "total": 83,
  "changes": 78,
  "sync": true
}

Response when no changes are pending sync.

{
  "total": 25,
  "changes": 0,
  "sync": false
}

hub.get

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Retrieves the current Notehub configuration for the Notecard.

Examples:

Retrieve the current Notehub configuration for the Notecard.

{
  "req": "hub.get"
}

Response

Response containing the current Notehub configuration for the Notecard.

Parameters:

Parameter	Type	Description	Default
device	string	The DeviceUID for the Notecard.	-
host	string	The URL of the Notehub host.	-
inbound	integer	The max wait time, in minutes, to sync inbound data from Notehub.	-
mode	string	The current operating mode of the Notecard, as defined in hub.set.	-
outbound	integer	The max wait time, in minutes, to sync outbound data from the Notecard.	-
product	string	The ProductUID to which the Notecard is registered.	-
sn	string	The serial number of the device, if set.	-
sync	boolean	true if the device is in continuous mode and set to sync every time a change is detected.	-
vinbound	string	If inbound has been overridden with a voltage-variable value.	-
voutbound	string	If outbound is overridden with a voltage-variable value.	-

Examples:

Response with current Notehub configuration settings.

{
  "device": "dev:000000000000000",
  "product": "com.your-company.your-name:your_product",
  "mode": "periodic",
  "outbound": 60,
  "inbound": 240,
  "host": "a.notefile.net",
  "sn": "your-serial-number"
}

hub.log

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

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
alert	boolean	true if the message is urgent. This doesn't change any functionality, but rather alert is provided as a convenient flag to use in your program logic.	-
sync	boolean	true if a sync should be initiated immediately. Setting true will also remove the Notecard from certain types of penalty boxes.	-
text	string	Text to log.	-

Examples:

Log an urgent health alert and sync immediately.

{
  "req": "hub.log",
  "text": "something is wrong!",
  "alert": true,
  "sync": true
}

Log a simple text message.

{
  "req": "hub.log",
  "text": "System status: normal"
}

Response

Response from logging a device health message to Notehub.

No specific parameters defined.

hub.set

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
align	boolean	Use true to align syncs on a regular time-periodic cycle.	-
details	['string', 'object']	When using Notecard LoRa you can use this argument to provide information about an alternative LoRaWAN server or service you would like the Notecard to use. The argument you provide must be a JSON object with three keys, "deveui", "appeui", and "appkey", all of which are hexadecimal strings with no leading 0x. For example: {"deveui":"0080E11500088B37","appeui":"6E6F746563617264","appkey":"00088B37"} The LoRaWAN details you send to a Notecard become part of its permanent configuration, and survive factory resets. You can reset a Notecard's LoRaWAN details to its default values by providing a "-" for the details argument.	-
duration	integer	When in continuous mode, the amount of time, in minutes, of each session (the minimum allowed value is 15). When this time elapses, the Notecard gracefully ends the current session and starts a new one in order to sync session-specific data to Notehub.	-
host	string	The URL of the Notehub service. Use "-" to reset to the default value.	-
inbound	integer	The max wait time, in minutes, to sync inbound data from Notehub. Explicit syncs (e.g. using hub.sync) do not affect this cadence. When in periodic or continuous mode this argument is required, otherwise the Notecard will function as if it is in minimum mode as it pertains to syncing behavior. Use -1 to reset the value back to its default of 0. A value of 0 means that the Notecard will never sync inbound data unless explicitly told to do so (e.g. using hub.sync).	-
mode	string	The Notecard's synchronization mode. Allowed Values: "periodic": Periodically connect to the Notehub. This is the default value set on each Notecard after a factory reset. "continuous": Enables an always-on network connection, for high power devices. Outbound data still syncs periodically, unless specified in a Note or File request. "minimum": Disables periodic connection. The Notecard will not sync until it receives an explicit hub.sync request. OTA DFU updates are not available when using this mode. "off": Disables automatic and manual syncs. hub.sync requests will be ignored in this mode. OTA DFU updates are not available when using this mode. "dfu": Puts the Notecard in DFU mode for IAP host MCU firmware updates. This mode is effectively the same as off in terms of the Notecard's network and Notehub connections.	-
off	boolean	Set to true to manually instruct the Notecard to resume periodic mode after a web transaction has completed.	-
on	boolean	If in periodic mode, used to temporarily switch the Notecard to continuous mode to perform a web transaction.\n\nIgnored if the Notecard is already in continuous mode or if the Notecard is NOT performing a web transaction.	-
outbound	integer	The max wait time, in minutes, to sync outbound data from the Notecard. Explicit syncs (e.g. using hub.sync) do not affect this cadence. When in periodic or continuous mode this argument is required, otherwise the Notecard will function as if it is in minimum mode as it pertains to syncing behavior. Use -1 to reset the value back to its default of 0. A value of 0 means that the Notecard will never sync outbound data unless explicitly told to do so (e.g. using hub.sync).	-
product	string	A Notehub-managed unique identifier that is used to match Devices with Projects. This string is used during a device's auto-provisioning to find the Notehub Project that, once provisioned, will securely manage the device and its data.	-
seconds	integer	If in periodic mode and using on above, the number of seconds to run in continuous mode before switching back to periodic mode. If not set, a default of 300 seconds is used. Ignored if the Notecard is already in continuous mode.	-
sn	string	The end product's serial number.	-
sync	boolean	If in continuous mode, automatically and immediately sync each time an inbound Notefile change is detected on Notehub. NOTE: The sync argument is not supported when a Notecard is in NTN mode.	-
umin	boolean	Set to true to use USB/line power variable sync behavior, enabling the Notecard to stay in continuous mode when connected to USB/line power and fallback to minimum mode when disconnected.	-
uoff	boolean	Set to true to use USB/line power variable sync behavior, enabling the Notecard to stay in continuous mode when connected to USB/line power and fallback to off mode when disconnected.	-
uperiodic	boolean	Set to true to use USB/line power variable sync behavior, enabling the Notecard to stay in continuous mode when connected to USB/line power and fallback to periodic mode when disconnected.	-
version	['string', 'object']	The version of your host firmware. The value provided will appear on your device in Notehub under the "Host Firmware" tab. You may pass a simple version number string (e.g. "1.0.0.0"), or an object with detailed information about the firmware image. If you provide an object it must take the following form. {"org":"my-organization","product":"My Product","description":"A description of the image","version":"1.2.4","built":"Jan 01 2025 01:02:03","ver_major":1,"ver_minor":2,"ver_patch":4,"ver_build": 5,"builder":"The Builder"} If your project uses Notecard Outboard Firmware Update, you can alternatively use the dfu.status request to set your host firmware version.	-
vinbound	string	Overrides inbound with a voltage-variable value. Use "-" to clear this value. NOTE: Setting voltage-variable values is not supported on Notecard XP.	-
voutbound	string	Overrides outbound with a voltage-variable value. Use "-" to clear this value. NOTE: Setting voltage-variable values is not supported on Notecard XP.	-

Examples:

Change device ProductUID and serial number.

{
  "req": "hub.set",
  "product": "com.your-company.your-name:your_product",
  "sn": "my-device"
}

Configure periodic mode with outbound and inbound sync timing.

{
  "req": "hub.set",
  "mode": "periodic",
  "product": "com.your-company.your-name:your_product",
  "outbound": 90,
  "inbound": 240
}

Configure continuous mode with session duration and automatic sync.

{
  "req": "hub.set",
  "mode": "continuous",
  "product": "com.your-company.your-name:your_product",
  "outbound": 30,
  "inbound": 60,
  "duration": 240,
  "sync": true
}

Configure voltage-dependent synchronization periods.

{
  "req": "hub.set",
  "mode": "periodic",
  "voutbound": "usb:30;high:60;normal:90;low:120;dead:0",
  "vinbound": "usb:60;high:120;normal:240;low:480;dead:0"
}

Set host firmware version using a simple string.

{
  "req": "hub.set",
  "version": "1.2.3"
}

Set host firmware version using detailed object information.

{
  "req": "hub.set",
  "version": {
    "org": "my-organization",
    "product": "My Product",
    "description": "A description of the image",
    "version": "1.2.4",
    "built": "Jan 01 2025 01:02:03",
    "ver_major": 1,
    "ver_minor": 2,
    "ver_patch": 4,
    "ver_build": 5,
    "builder": "The Builder"
  }
}

Set alternative LoRaWAN server details for Notecard LoRa.

{
  "req": "hub.set",
  "details": {
    "deveui": "0080E11500088B37",
    "appeui": "6E6F746563617264",
    "appkey": "00088B3700112233445566778899AABB"
  }
}

Reset LoRaWAN details to default values using dash.

{
  "req": "hub.set",
  "details": "-"
}

Configure USB/line power variable sync to minimum mode.

{
  "req": "hub.set",
  "umin": true
}

Temporarily switch to continuous mode for web transactions.

{
  "req": "hub.set",
  "on": true,
  "seconds": 300
}

Response

Response from configuring the Notecard's Notehub connection and sync behavior.

No specific parameters defined.

hub.signal

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Receive a Signal (a near-real-time Note) from Notehub.

This request checks for an inbound signal from Notehub. If it finds a signal, this request returns the signal's body and deletes the signal. If there are multiple signals to receive, this request reads and deletes signals in FIFO (first in first out) order.

Parameters:

Parameter	Type	Description	Default
seconds	integer	The number of seconds to wait before timing out the request.	-

Examples:

Check for an inbound signal from Notehub.

{
  "req": "hub.signal"
}

Check for an inbound signal with custom timeout.

{
  "req": "hub.signal",
  "seconds": 30
}

Response

Response containing a received signal from Notehub.

Parameters:

Parameter	Type	Description	Default
body	object	The JSON body of a received signal.	-
connected	boolean	true if the Notecard is connected to Notehub.	-
signals	integer	The number of queued signals remaining.	-

Examples:

Response when a signal is received from Notehub.

{
  "body": {
    "example-key": "example-value"
  },
  "connected": true
}

Response when no signals are available.

{
  "connected": true,
  "signals": 0
}

Response with remaining queued signals.

{
  "body": {
    "data": "signal-data"
  },
  "connected": true,
  "signals": 3
}

hub.status

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

Examples:

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

{
  "req": "hub.status"
}

Response

Response containing the current status of the Notecard's connection to Notehub.

Parameters:

Parameter	Type	Description	Default
connected	boolean	true if the Notecard is connected to Notehub.	-
status	string	Details about the Notecard's transport (e.g. cellular, Wi-Fi, LoRa) connection status. Use connected to check if the Notecard is connected to Notehub.	-

Examples:

Response when Notecard is connected to Notehub.

{
  "status": "connected (session open) {connected}",
  "connected": true
}

Response when Notecard is not connected to Notehub.

{
  "status": "disconnected",
  "connected": false
}

hub.sync

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

Manually initiates a sync with Notehub.

Parameters:

Parameter	Type	Description	Default
allow	boolean	Set to true to remove the Notecard from certain types of penalty boxes (the default is false).	-
in	boolean	Set to true to only sync pending inbound Notefiles. Required when using NTN mode with Starnote to check for inbound Notefiles.	-
out	boolean	Set to true to only sync pending outbound Notefiles.	-

Examples:

Initiate a manual sync with Notehub.

{
  "req": "hub.sync"
}

Sync and remove Notecard from penalty boxes.

{
  "req": "hub.sync",
  "allow": true
}

Sync only pending outbound Notefiles.

{
  "req": "hub.sync",
  "out": true
}

Sync only pending inbound Notefiles (required for NTN mode).

{
  "req": "hub.sync",
  "in": true
}

Response

Response from manually initiating a sync with Notehub.

No specific parameters defined.

hub.sync.status

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
sync	boolean	true if this request should auto-initiate a sync pending outbound data.	-

Examples:

Check the status of a recent or previous sync.

{
  "req": "hub.sync.status"
}

Check sync status and auto-initiate sync if there is pending outbound data.

{
  "req": "hub.sync.status",
  "sync": true
}

Response

Response containing the status of a recently triggered or previous sync.

Parameters:

Parameter	Type	Description	Default
alert	boolean	true if an error occurred during the most recent sync.	-
completed	integer	Number of seconds since the last sync completion.	-
mode	string	The current state of the wireless connectivity module in use.	-
requested	integer	Number of seconds since the last explicit sync request.	-
scan	boolean	Returns true if triangulation data was sent to Notehub in the most recent sync.	-
seconds	integer	If the Notecard is in a Penalty Box, the number of seconds until the penalty condition ends.	-
status	string	The status of the current or previous sync. Refer to this listing for the meaning of the various status codes returned (e.g. {sync-end}).	-
sync	boolean	true if the notecard has unsynchronized notes, or requires a sync to set its internal clock.	-
time	integer	Time of the last sync completion. Will only populate if the Notecard has completed a sync to Notehub to obtain the time.	-

Examples:

Response showing sync status with completion time and alert.

{
  "status": "completed {sync-end}",
  "mode": "{modem-off}",
  "time": 1598367163,
  "alert": true,
  "sync": true,
  "completed": 1648
}

Response when Notecard is in penalty box.

{
  "status": "waiting {network-down}",
  "mode": "{modem-off}",
  "sync": false,
  "seconds": 300
}

Response showing recent sync with scan data.

{
  "status": "completed {sync-end}",
  "mode": "{modem-off}",
  "time": 1598367163,
  "sync": false,
  "completed": 45,
  "scan": true
}

note.add

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
binary	boolean	If true, the Notecard will send all the data in the binary buffer to Notehub. Learn more in this guide on Sending and Receiving Large Binary Objects.	-
body	object	A JSON object to be enqueued. A Note must have either a body or a payload, and can have both.	-
file	string	The name of the Notefile. On Notecard LoRa this argument is required. On all other Notecards this field is optional and defaults to data.qo if not provided. When using this request on the Notecard the Notefile name must end in one of: .qo for a queue outgoing (Notecard to Notehub) with plaintext transport .qos for a queue outgoing with encrypted transport .db for a bidirectionally synchronized database with plaintext transport .dbs for a bidirectionally synchronized database with encrypted transport .dbx for a local-only database	data.qo
full	boolean	If set to true, and the Note is using a Notefile Template, the Note will bypass usage of omitempty and retain null, 0, false, and empty string "" values.	-
key	string	The name of an environment variable in your Notehub.io project that contains the contents of a public key. Used when encrypting the Note body for transport.	-
limit	boolean	If set to true, the Note will not be created if Notecard is in a penalty box.	-
live	boolean	If true, bypasses saving the Note to flash on the Notecard. Required to be set to true if also using "binary":true.	-
max	integer	Defines the maximum number of queued Notes permitted in the specified Notefile ("file"). Any Notes added after this value will be rejected. When used with "sync":true, a sync will be triggered when the number of pending Notes matches the max value.	-
note	string	If the Notefile has a .db/.dbs/.dbx extension, specifies a unique Note ID. If note string is "?", then a random unique Note ID is generated and returned as {"note":"xxx"}. If this argument is provided for a .qo Notefile, an error is returned.	-
payload	string	A base64-encoded binary payload. A Note must have either a body or a payload, and can have both. If a Note template is not in use, payloads are limited to 250 bytes.	-
sync	boolean	Set to true to sync immediately. Only applies to outgoing Notecard requests, and only guarantees syncing the specified Notefile. Auto-syncing incoming Notes from Notehub is set on the Notecard with {"req": "hub.set", "mode":"continuous", "sync": true}.	-
verify	boolean	If set to true and using a templated Notefile, the Notefile will be written to flash immediately, rather than being cached in RAM and written to flash later.	-

Examples:

Add a Note with JSON body data and trigger immediate sync.

{
  "req": "note.add",
  "file": "sensors.qo",
  "body": {
    "temp": 72.22
  },
  "sync": true
}

Response

Response containing information about the added Note.

Parameters:

Parameter	Type	Description	Default
note	string	The generated unique Note ID when note parameter was set to "?".	-
template	boolean	true when a template is active on the Notefile.	-
total	integer	The total number of Notes in the Notefile.	-

Examples:

Response showing total notes after adding to a Notefile.

{
  "total": 12
}

note.changes

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Used to incrementally retrieve changes within a specific Notefile.

Parameters:

Parameter	Type	Description	Default
delete	boolean	true to delete the Notes returned by the request.	-
deleted	boolean	true to return deleted Notes with this request. Deleted Notes are only persisted in a database notefile (.db/.dbs) between the time of Note deletion on the Notecard and the time that a sync with Notehub takes place. As such, this boolean will have no effect after a sync or on queue notefiles (.q*).	-
file	string	The Notefile ID.	-
max	integer	The maximum number of Notes to return in the request.	-
reset	boolean	true to reset a change tracker.	-
start	boolean	true to reset the tracker to the beginning.	-
stop	boolean	true to delete the tracker.	-
tracker	string	The change tracker ID. This value is developer-defined and can be used across both the note.changes and file.changes requests.	-

Examples:

Check changes in a Notefile with a tracker starting from the beginning.

{
  "req": "note.changes",
  "file": "my-settings.db",
  "tracker": "inbound-tracker",
  "start": true
}

Retrieve and delete up to 2 changes from a Notefile.

{
  "req": "note.changes",
  "file": "my-settings.db",
  "tracker": "inbound-tracker",
  "start": true,
  "delete": true,
  "max": 2
}

Get changes from a Notefile without a tracker.

{
  "req": "note.changes",
  "file": "data.db"
}

Reset a change tracker to start from the beginning.

{
  "req": "note.changes",
  "file": "events.db",
  "tracker": "event-tracker",
  "reset": true
}

Retrieve changes including deleted notes from database.

{
  "req": "note.changes",
  "file": "config.db",
  "tracker": "config-tracker",
  "deleted": true
}

Delete a change tracker when finished.

{
  "req": "note.changes",
  "file": "logs.db",
  "tracker": "log-tracker",
  "stop": true
}

Response

Response containing incremental changes from a specific Notefile.

Parameters:

Parameter	Type	Description	Default
changes	integer	The number of pending changes in the Notefile.	-
notes	object	An object with a key for each Note (the Note ID in a DB Notefile or an internally-generated ID for .qo and .qi Notes) and value object with the body of each Note and the time the Note was added.	-
total	integer	The total number of Notes in the Notefile.	-

Examples:

Response showing changes with Note details and timestamps.

{
  "changes": 4,
  "total": 4,
  "notes": {
    "setting-one": {
      "body": {
        "foo": "bar"
      },
      "time": 1598918235
    },
    "setting-two": {
      "body": {
        "foo": "bat"
      },
      "time": 1598918245
    },
    "setting-three": {
      "body": {
        "foo": "baz"
      },
      "time": 1598918225
    },
    "setting-four": {
      "body": {
        "foo": "foo"
      },
      "time": 1598910532
    }
  }
}

Response when no changes are available.

{
  "changes": 0,
  "total": 10,
  "notes": {}
}

Response with a single Note change.

{
  "changes": 1,
  "total": 5,
  "notes": {
    "config-update": {
      "body": {
        "brightness": 75,
        "volume": 50
      },
      "time": 1609459200
    }
  }
}

note.delete

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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	The Notefile from which to delete a Note. Must be a Notefile with a .db or .dbx extension.	-
note	string	The Note ID of the Note to delete.	-
verify	boolean	If set to true and using a templated Notefile, the Notefile will be written to flash immediately, rather than being cached in RAM and written to flash later.	-

Examples:

Delete a specific Note by ID from a database Notefile.

{
  "req": "note.delete",
  "file": "my-settings.db",
  "note": "measurements"
}

Delete a Note and write to flash immediately for a templated Notefile.

{
  "req": "note.delete",
  "file": "config.db",
  "note": "display-settings",
  "verify": true
}

Delete a Note using command syntax (no response expected).

{
  "cmd": "note.delete",
  "file": "temp-data.db",
  "note": "sensor-reading"
}

Response

Response confirming Note deletion from a DB Notefile.

No specific parameters defined.

note.get

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

.qo/.qos Notes must be read from the Notehub event table using the Notehub Event API.

Parameters:

Parameter	Type	Description	Default
decrypt	boolean	true to decrypt encrypted inbound Notefiles.	-
delete	boolean	true to delete the Note after retrieving it.	-
deleted	boolean	true to allow retrieval of a deleted Note.	-
file	string	The Notefile name must end in .qi (for plaintext transport), .qis (for encrypted transport), .db or .dbx (for local-only DB Notefiles).	data.qi
note	string	If the Notefile has a .db or .dbx extension, specifies a unique Note ID. Not applicable to .qi Notefiles.	-

Examples:

Retrieve and delete a Note from an inbound queue file.

{
  "req": "note.get",
  "file": "requests.qi",
  "delete": true
}

Read a specific Note from a database Notefile.

{
  "req": "note.get",
  "file": "my-settings.db",
  "note": "measurements"
}

Retrieve from the default data.qi Notefile.

{
  "req": "note.get"
}

Retrieve a deleted Note from a .db Notefile.

{
  "req": "note.get",
  "file": "config.db",
  "note": "old-setting",
  "deleted": true
}

Retrieve and decrypt an encrypted inbound Note.

{
  "req": "note.get",
  "file": "secure.qis",
  "decrypt": true
}

Response

Response containing a Note retrieved from a Notefile.

Parameters:

Parameter	Type	Description	Default
body	object	The JSON body, if contained in the Note.	-
payload	string	The payload, if contained in the Note.	-
time	integer	The time the Note was added to the Notecard or Notehub.	-

Examples:

Response showing note with JSON body and timestamp.

{
  "body": {
    "api-key1": "api-val1"
  },
  "time": 1598909219
}

note.template

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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.

Read about Working with Note Templates for additional information.

Parameters:

Parameter	Type	Description	Default
body	object	A sample JSON body that specifies field names and values as "hints" for the data type. Possible data types are: boolean, integer, float, and string. See Understanding Template Data Types for an explanation of type hints and explanations.	-
delete	boolean	Set to true to delete all pending Notes using the template if one of the following scenarios is also true: Connecting via non-NTN (e.g. cellular or Wi-Fi) communications, but attempting to sync NTN-compatible Notefiles. or Connecting via NTN (e.g. satellite) communications, but attempting to sync non-NTN-compatible Notefiles. Read more about this feature in Starnote Best Practices.	-
file	string	The name of the Notefile to which the template will be applied.	-
format	string	By default all Note templates automatically include metadata, including a timestamp for when the Note was created, various fields about a device's location, as well as a timestamp for when the device's location was determined. By providing a format of "compact" you tell the Notecard to omit this additional metadata to save on storage and bandwidth. The use of format: "compact" is required for Notecard LoRa and a Notecard paired with Starnote. When using "compact" templates, you may include the following keywords in your template to add in fields that would otherwise be omitted: _lat, _lon, _ltime, _time. See Creating Compact Templates to learn more.	-
length	integer	The maximum length of a payload (in bytes) that can be sent in Notes for the template Notefile. As of v3.2.1 length is not required, and payloads can be added to any template-based Note without specifying the payload length.	-
port	integer	This argument is required on Notecard LoRa and a Notecard paired with Starnote, but ignored on all other Notecards. A port is a unique integer in the range 1–100, where each unique number represents one Notefile. This argument allows the Notecard to send a numerical reference to the Notefile over the air, rather than the full Notefile name. The port you provide is also used in the "frame port" field on LoRaWAN gateways.	-
verify	boolean	If true, returns the current template set on a given Notefile.	-

Examples:

Provide a template schema for the readings.qo Notefile with sample data.

{
  "req": "note.template",
  "file": "readings.qo",
  "body": {
    "new_vals": true,
    "temperature": 14.1,
    "humidity": 11,
    "pump_state": "4"
  }
}

Set up a compact template for LoRa transmission on port 50 to reduce bandwidth usage.

{
  "req": "note.template",
  "file": "readings.qo",
  "body": {
    "new_vals": true,
    "temperature": 14.1,
    "humidity": 11,
    "pump_state": "4"
  },
  "format": "compact",
  "port": 50
}

Set up a compact template including location and timestamp fields for comprehensive sensor data.

{
  "req": "note.template",
  "file": "readings.qo",
  "body": {
    "temperature": 14.1,
    "_lat": 14.1,
    "_lon": 14.1,
    "_ltime": 14,
    "_time": 14
  },
  "format": "compact",
  "port": 50
}

Retrieve the current template configuration for the readings.qo Notefile.

{
  "req": "note.template",
  "file": "readings.qo",
  "verify": true
}

Response

No description available.

Parameters:

Parameter	Type	Description	Default
body	object	If the verify argument is provided and the Notefile has an active template, the template body.	-
bytes	integer	The number of bytes that will be transmitted to Notehub, per Note, before compression.	-
format	string	If the format argument is provided, this represents the format applied to the template.	-
length	integer	If the verify argument is provided and the Notefile has an active template with a payload, the payload length.	-
template	boolean	true if an active template exists on the Notefile.	-

Examples:

Response when template is successfully set, showing bytes per note.

{
  "bytes": 40
}

Response when verifying existing template with all fields.

{
  "template": true,
  "body": {
    "temperature": 14.1,
    "humidity": 11
  },
  "bytes": 40
}

Response showing compact format template.

{
  "template": true,
  "format": "compact",
  "bytes": 25
}

note.update

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
body	object	A JSON object to add to the Note. A Note must have either a body or payload, and can have both.	-
file	string	The name of the DB Notefile that contains the Note to update.	-
note	string	The unique Note ID.	-
payload	string	A base64-encoded binary payload. A Note must have either a body or payload, and can have both.	-
verify	boolean	If set to true and using a templated Notefile, the Notefile will be written to flash immediately, rather than being cached in RAM and written to flash later.	-

Examples:

Update a Note with new JSON body content.

{
  "req": "note.update",
  "file": "my-settings.db",
  "note": "measurements",
  "body": {
    "interval": 60
  }
}

Update a Note with new base64 payload data.

{
  "req": "note.update",
  "file": "data.db",
  "note": "sensor-1",
  "payload": "SGVsbG8gV29ybGQ="
}

Update a Note with both body and payload.

{
  "req": "note.update",
  "file": "config.db",
  "note": "device-config",
  "body": {
    "enabled": true
  },
  "payload": "YWRkaXRpb25hbERhdGE="
}

Update a Note in a templated Notefile with immediate flash write.

{
  "req": "note.update",
  "file": "template.db",
  "note": "user-setting",
  "body": {
    "theme": "dark"
  },
  "verify": true
}

Update a Note using command syntax (no response expected).

{
  "cmd": "note.update",
  "file": "cache.db",
  "note": "temp-data",
  "body": {
    "status": "updated"
  }
}

Response

Response confirming Note update in a DB Notefile.

No specific parameters defined.

ntn.gps

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

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
off	boolean	When true, a paired Starnote will use its own GPS/GNSS location. This is the default configuration.	-
on	boolean	When true, a Starnote will use the GPS/GNSS location from its paired Notecard, instead of its own GPS/GNSS location.	-

Examples:

Configure Starnote to use the paired Notecard's GPS/GNSS location.

{
  "req": "ntn.gps",
  "on": true
}

Configure Starnote to use its own GPS/GNSS location (default).

{
  "req": "ntn.gps",
  "off": true
}

Request current GPS/GNSS location configuration.

{
  "req": "ntn.gps"
}

Response

Response indicating current Starnote GPS/GNSS location configuration.

Parameters:

Parameter	Type	Description	Default
off	boolean	Returned and true if a paired Starnote will use its own GPS/GNSS location.	-
on	boolean	Returned and true if a Starnote will use the GPS/GNSS location from its paired Notecard.	-

Examples:

Response indicating Starnote is using its own GPS/GNSS location (default).

{
  "off": true
}

Response indicating Starnote is using paired Notecard's GPS/GNSS location.

{
  "on": true
}

ntn.reset

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

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.

Examples:

Clear Starnote configuration to return to testing NTN mode over cellular or Wi-Fi.

{
  "req": "ntn.reset"
}

Response

Empty response confirming Starnote configuration reset.

No specific parameters defined.

ntn.status

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

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

Examples:

Request current status of Notecard's connection to paired Starnote.

{
  "req": "ntn.status"
}

Response

Response showing current status of Notecard's connection to paired Starnote.

Parameters:

Parameter	Type	Description	Default
err	string	This member is present if any errors have occurred while connecting to a paired Starnote, for example: {"err":"no NTN module is connected {no-ntn-module}"}	-
status	string	Details about a Notecard's connection to a paired Starnote, for example: {"status":"{ntn-idle}{ntn-unknown-location}"}	-

Examples:

Response showing Starnote connection in idle state.

{
  "status": "{ntn-idle}"
}

Response showing error when no NTN module is connected.

{
  "err": "no NTN module is connected {no-ntn-module}"
}

Response showing detailed status including location information.

{
  "status": "{ntn-idle}{ntn-unknown-location}"
}

var.delete

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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
file	string	The name of the DB Notefile that contains the Note to delete. Default value is vars.db.	-
name	string	The unique Note ID.	-

Examples:

Delete a variable named "status" from the default vars.db DB Notefile.

{
  "req": "var.delete",
  "name": "status"
}

Delete a variable named "temperature" from the "sensors.db" DB Notefile.

{
  "req": "var.delete",
  "name": "temperature",
  "file": "sensors.db"
}

Response

Response confirming deletion of a variable from a DB Notefile.

No specific parameters defined.

var.get

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

Request

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

Parameters:

Parameter	Type	Description	Default
file	string	The name of the DB Notefile that contains the Note to retrieve. Default value is vars.db.	-
name	string	The unique Note ID.	-

Examples:

Retrieve a variable named "status" from the default vars.db DB Notefile.

{
  "req": "var.get",
  "name": "status"
}

Retrieve a variable named "temperature" from the sensors.db DB Notefile.

{
  "req": "var.get",
  "name": "temperature",
  "file": "sensors.db"
}

Response

Response containing a Note value from a DB Notefile.

Parameters:

Parameter	Type	Description	Default
flag	boolean	The boolean value stored in the DB Notefile.	-
text	string	The string-based value stored in the DB Notefile.	-
value	number	The numeric value stored in the DB Notefile.	-

Examples:

Response containing a string value from the DB Notefile.

{
  "text": "open"
}

Response containing a numeric value from the DB Notefile.

{
  "value": 42
}

Response containing a boolean value from the DB Notefile.

{
  "flag": true
}

var.set

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI LORA WIFI

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
file	string	The name of the DB Notefile that contains the Note to add or update. Default value is vars.db.	-
flag	boolean	The boolean value to be stored in the DB Notefile.	-
name	string	The unique Note ID.	-
sync	boolean	Set to true to immediately sync any changes.	-
text	string	The string-based value to be stored in the DB Notefile.	-
value	integer	The numeric value to be stored in the DB Notefile.	-

Examples:

Set a text variable named "status" to "open" in the default vars.db DB Notefile.

{
  "req": "var.set",
  "name": "status",
  "text": "open"
}

Set a numeric variable named "temperature" to 23 in a specific DB Notefile.

{
  "req": "var.set",
  "name": "temperature",
  "value": 23,
  "file": "sensors.db"
}

Set a boolean variable named "active" to true and immediately sync changes.

{
  "req": "var.set",
  "name": "active",
  "flag": true,
  "sync": true
}

Response

Response confirming successful addition or update of a Note in a DB Notefile.

No specific parameters defined.

web

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

SKUs

CELL CELL+WIFI WIFI

Request

Performs an HTTP or HTTPS request against an external endpoint, with the ability to specify any valid HTTP method.

Parameters:

Parameter	Type	Description	Default
content	string	The MIME type of the body or payload of the response. Default is application/json.	-
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).	-
route	string	Alias for a Proxy Route in Notehub.	-

Examples:

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

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

Response

Response containing the result of an HTTP or HTTPS request to an external endpoint.

Parameters:

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

Examples:

Response from a web request

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

web.delete

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

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
async	boolean	If true, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub.	-
content	string	The MIME type of the body or payload of the response. Default is application/json.	application/json
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.	-
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).	-
note	string	The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).	-
route	string	Alias for a Proxy Route in Notehub.	-
seconds	integer	If specified, overrides the default 90 second timeout.	90

Examples:

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

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

Response

Response containing the result of an HTTP or HTTPS DELETE request to an external endpoint.

Parameters:

Parameter	Type	Description	Default
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.	-
result	integer	The HTTP Status Code	-
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

Version Information

Schema Version: 0.3.1 | API Version: 9.1.1

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
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. Learn more in this guide on Sending and Receiving Large Binary Objects.	-
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.	-
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.	-
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.	-
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).	-
note	string	The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).	-
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.	-
route	string	Alias for a Proxy Route in Notehub.	-
seconds	integer	If specified, overrides the default 90 second timeout.	-

Examples:

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

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

Response

Response containing the result of an HTTP or HTTPS GET request to an external endpoint.

Parameters:

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

Examples:

Response body from HTTP GET request to the external service.

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

web.post

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

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
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 send all the data in the binary buffer to the specified proxy route in Notehub. Learn more in this guide on Sending and Receiving Large Binary Objects.	-
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.	application/json
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.	-
max	integer	The maximum size of the response from the remote server, in bytes. Useful if a memory-constrained host wants to limit the response size.	-
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).	-
note	string	The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).	-
offset	integer	When sending payload fragments, the number of bytes of the binary payload to offset from 0 when reassembling on the Notehub once all fragments have been received.	-
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. Learn more about sending large binary objects with the Notecard.	-
route	string	Alias for a Proxy Route in Notehub.	-
seconds	integer	If specified, overrides the default 90 second timeout.	90
status	string	A 32-character hex-encoded MD5 sum of the payload or payload fragment. Used by Notehub to perform verification upon receipt.	-
total	integer	When sending large payloads to Notehub in fragments across several web.post requests, the total size, in bytes, of the binary payload across all fragments.	-
verify	boolean	true to request verification from Notehub once the payload or payload fragment is received. Automatically set to true when status is supplied.	-

Examples:

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

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

Response

Response containing the result of an HTTP or HTTPS POST request to an external endpoint.

Parameters:

Parameter	Type	Description	Default
body	object	The JSON response body from the external service, if any. The maximum response size from the service is 8192 bytes.	-
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).	-
payload	string	A base64-encoded binary payload from the external service, if any. The maximum response size from the service is 8192 bytes.	-
result	integer	The HTTP Status Code.	-
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": 201
}

web.put

Version Information

Schema Version: 0.2.1 | API Version: 9.1.1

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
async	boolean	If true, the Notecard performs the web request asynchronously, and returns control to the host without waiting for a response from Notehub.	-
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.	application/json
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.	-
max	integer	The maximum size of the response from the remote server, in bytes. Useful if a memory-constrained host wants to limit the response size. Default (and maximum value) is 8192.	8192
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).	-
note	string	The unique Note ID for the local-only Database Notefile (.dbx). Only used with asynchronous web requests (see file argument above).	-
offset	integer	When sending payload fragments, the number of bytes of the binary payload to offset from 0 when reassembling on the Notehub once all fragments have been received.	-
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. Learn more about sending large binary objects with the Notecard.	-
route	string	Alias for a Proxy Route in Notehub.	-
seconds	integer	If specified, overrides the default 90 second timeout.	90
status	string	A 32-character hex-encoded MD5 sum of the payload or payload fragment. Used by Notehub to perform verification upon receipt.	-
total	integer	When sending large payloads to Notehub in fragments across several web.put requests, the total size, in bytes, of the binary payload across all fragments.	-
verify	boolean	true to request verification from Notehub once the payload or payload fragment is received. Automatically set to true when status is supplied.	-

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

Response containing the result of an HTTP or HTTPS PUT request to an external endpoint.

Parameters:

Parameter	Type	Description	Default
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.	-
result	integer	The HTTP Status Code.	-
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
}