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.
When sending this request to the Notecard, if a Notefile
name is specified, the file must either be a DB
Notefile or outbound queue file (.qo/.qos). When sending this request
to Notehub, the file must either be a DB Notefile or an inbound queue file
(.qi/.qis).
file
string (Default: data.qo or data.qi)
On the Notecard, the notefile name must end in .qo (for plaintext transport),
.qos (for encrypted transport), or .db.
On Notehub, the Notefile must end in .qi (for plaintext transport),
.qis (for encrypted transport), or .db.
note
string (optional)
If the Notefile has a .db extension, specifies a unique Note ID. Note:
if this argument is provided for a .qi or .qo Notefile, an error
is returned.
body
JSON object
A JSON object to be enqueued. A note must have either a body or a payload,
and can have both.
payload
base64 string
A base64-encoded binary payload. A note must have either a body or a payload,
and can have both.
sync
boolean (optional)
true to sync immediately. Only applies to Notecard requests. Auto-syncing
of Notes from Notehub to the Notecard is set-up 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.
Response Members
total
The total number of Notes in the Notefile.
template
true when a template is active on the Notefile.
{ "total": 12 }
Used to incrementally retrieve changes within a specific Notefile.
file
string
The Notefile ID.
tracker
The change tracker ID. This value is developer-defined and can be used
across both the note.changes and file.changes requests.
max
integer (optional)
The maximum number of Notes to return in the request.
start
boolean (optional)
true to reset the tracker to the beginning.
stop
boolean (optional)
true to delete the tracker.
deleted
boolean (optional)
true to return deleted Notes with this request.
delete
boolean (optional)
true to delete the Notes returned by the request.
Response Members
total
integer
The total number of Notes in the Notefile.
changes
integer
The number of pending changes in the Notefile.
notes
JSON 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. _Note: to delete
Notes from a .qi Notefile, use note.get or note.changes with
delete:true.
file
string
The Notefile from which to delete a Note. Must be a Notefile with
a .db extension.
note
string
The Note ID of the Note to delete.
Response Members
{} means success.Retrieves a Note from a Notefile. When sending this request to the Notecard,
the file must either be a DB Notefile (.db) or inbound queue file
(.qi/.qis). When sending this request to Notehub, the file must be a DB
Notefile (.db). .qo/.qos Notes must be read from the Notehub event
table using a hub.app.data.query request.
file
string (Default: data.qi or data.qo)
On the Notecard, the notefile name must end in .qi (for plaintext transport),
.qis (for encrypted transport), or .db.
On Notehub, the Notefile must end in .db.
note
string (optional)
If the Notefile has a .db extension, specifies a unique Note ID. Not
applicable to .qi and .qo Notefiles.
delete
boolean (optional)
true to delete the Note after retrieving it.
deleted
boolean (optional)
true to allow retrieval of a deleted Note.
Response Members
body
JSON object
The JSON body, if contained in the Note.
payload
base64 string
The payload, if contained in the Note.
time
UNIX 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.
file
string
The name of the DB Notefile that contains the Note to update.
note
string
The unique Note ID.
body
JSON object
A JSON object to add to the Note. A Note must have either a body or
payload, and can have both.
payload
base64 string
A base64-encoded binary payload. A Note must have either a body or
payload, and can have both.
Response Members
{} 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.
file
string
The name of the Notefile to which the template will be applied.
body
JSON 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.
length
integer (optional)
If provided, the maximum length of a payload that can be sent in Notes
for the template Notefile.
Response Members
bytes
integer
The number of bytes that will be transmitted to Notehub, per Note, before compression.
{ "bytes": 40 }
