Rate this page Â
- ★★
- ★★
- ★★
- ★★
- ★★
Can we improve this page? Send us feedbackRate this page
- ★★
- ★★
- ★★
- ★★
- ★★
The note requests enable the quick creation and management of
Notes in
Notefiles. The requests in this section are
available on the Notecard API and Notehub API.
Adds a Note to a Notefile, creating the Notefile if it doesn't yet exist.
file argument below).file argument below).filestring (Default: data.qo or data.qi)
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
When used to add notes to Notehub, the Notefile must end in one of:
.qi for an incoming queue (Notehub to Notecard) with plaintext transport
.qis for an incoming queue (Notehub to Notecard) with encrypted transport
.db for a bidirectionally synchronized database with plaintext transport
.dbs for a bidirectionally synchronized database with encrypted transport
notestring (optional)
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"}. (Added in v1.5.6)
If this argument is provided for a .qi or .qo Notefile, an error is
returned.
bodyJSON object (optional)
A JSON object to be enqueued. A note must have either a body or a payload,
and can have both.
payloadbase64 string (optional)
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.
syncboolean (optional)
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}.
key (Added in v1.5.5)string (optional)
The name of an environment variable in your Notehub.io project that contains the contents of an RSA public key. Used when encrypting the Note body for transport. Only applies to Notecard requests.
verify (Added in v1.5.6)boolean (optional)
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.
authTokenstring (Notehub curl requests only)
A Notehub API authentication token.
projectUIDstring (Notehub curl requests only)
The ProjectUID of a Notehub project.
deviceUIDstring (Notehub curl requests only)
The globally-unique DeviceUID of a device that currently exists within the specified ProjectUID.
It can also accept a serial number by prefixing the serial number with sn:. Please note that the serial number must be URL encoded.
totalThe total number of Notes in the Notefile.
templatetrue when a template is active on the Notefile.
{ "total": 12 }
Used to incrementally retrieve changes within a specific Notefile.
filestring
The Notefile ID.
trackerstring (optional)
The change tracker ID. This value is developer-defined and can be used
across both the note.changes and file.changes requests.
maxinteger (optional)
The maximum number of Notes to return in the request.
startboolean (optional)
true to reset the tracker to the beginning.
stopboolean (optional)
true to delete the tracker.
deletedboolean (optional)
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*).
deleteboolean (optional)
true to delete the Notes returned by the request.
authTokenstring (Notehub curl requests only)
A Notehub API authentication token.
projectUIDstring (Notehub curl requests only)
The ProjectUID of a Notehub project.
deviceUIDstring (Notehub curl requests only)
The globally-unique DeviceUID of a device that currently exists within the specified ProjectUID.
It can also accept a serial number by prefixing the serial number with sn:. Please note that the serial number must be URL encoded.
totalinteger
The total number of Notes in the Notefile.
changesinteger
The number of pending changes in the Notefile.
notesJSON object
An object with a key for each Note (for instance, the Note ID in a
DB Notefile; For .qo and .qi Notes, these IDs are generated for
internal management) and value object with the body of each Note and the
Time the Note was added.
{ "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} } }
Deletes Notefiles from a DB Notefile by its Note ID. To delete
Notes from a .qi Notefile, use note.get or note.changes with
delete:true.
filestring
The Notefile from which to delete a Note. Must be a Notefile with
a .db or .dbx extension.
notestring
The Note ID of the Note to delete.
verify (Added in v1.5.6)boolean (optional)
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.
authTokenstring (Notehub curl requests only)
A Notehub API authentication token.
projectUIDstring (Notehub curl requests only)
The ProjectUID of a Notehub project.
deviceUIDstring (Notehub curl requests only)
The globally-unique DeviceUID of a device that currently exists within the specified ProjectUID.
It can also accept a serial number by prefixing the serial number with sn:. Please note that the serial number must be URL encoded.
{} means success.Retrieves a Note from a Notefile.
file argument below).file argument below)..qo/.qos Notes must be read from the Notehub event table using the
Notehub Event API.
filestring (Default: data.qi or data.qo)
On the Notecard, the notefile name must end in .qi (for plaintext transport),
.qis (for encrypted transport), .db or .dbx
(for local-only Database Notefiles).
On Notehub, the Notefile must end in .db.
notestring (optional)
If the Notefile has a .db or .dbx extension, specifies a unique Note ID. Not
applicable to .qi and .qo Notefiles.
deleteboolean (optional)
true to delete the Note after retrieving it.
Add as a URL parameter if using with a Notehub curl request (e.g. ?delete=true).
deletedboolean (optional)
true to allow retrieval of a deleted Note.
Add as a URL parameter if using with a Notehub curl request (e.g. ?deleted=true).
authTokenstring (Notehub curl requests only)
A Notehub API authentication token.
projectUIDstring (Notehub curl requests only)
The ProjectUID of a Notehub project.
deviceUIDstring (Notehub curl requests only)
The globally-unique DeviceUID of a device that currently exists within the specified ProjectUID.
It can also accept a serial number by prefixing the serial number with sn:. Please note that the serial number must be URL encoded.
bodyJSON object
The JSON body, if contained in the Note.
payloadbase64 string
The payload, if contained in the Note.
timeUNIX Epoch time
The time the Note was added to the Notecard or Notehub.
{ "body": { "api-key1": "api-val1" }, "time": 1598909219 }
Updates a Note in a DB Notefile by its ID, replacing the existing
body and/or payload.
filestring
The name of the DB Notefile that contains the Note to update.
notestring
The unique Note ID.
bodyJSON object
A JSON object to add to the Note. A Note must have either a body or
payload, and can have both.
payloadbase64 string
A base64-encoded binary payload. A Note must have either a body or
payload, and can have both.
verify (Added in v1.5.6)boolean (optional)
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.
authTokenstring (Notehub curl requests only)
A Notehub API authentication token.
projectUIDstring (Notehub curl requests only)
The ProjectUID of a Notehub project.
deviceUIDstring (Notehub curl requests only)
The globally-unique DeviceUID of a device that currently exists within the specified ProjectUID.
It can also accept a serial number by prefixing the serial number with sn:. Please note that the serial number must be URL encoded.
{} means success.Using the note.template request command 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.
filestring
The name of the Notefile to which the template will be applied.
bodyJSON object (optional)
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.
lengthinteger (optional)
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 no longer required, and
payloads can be added to any template-based Note without specifying the payload
length.
verify (Added in v3.2.1)boolean (optional)
If true, returns the current template set on a given Notefile.
bytesinteger
The number of bytes that will be transmitted to Notehub, per Note, before compression.
template (Added in v3.2.1)boolean
true if an active template exists on the Notefile.
body (Added in v3.2.1)If the verify argument is provided and the Notefile has an active template,
the template body
length (Added in v3.2.1)If the verify argument is provided and the Notefile has an active template
with a payload, the payload length.
{ "bytes": 40 }