Note API
The Note APIs enable the creation and management of Notes in inbound Notefiles or DB Notefiles.
Add Note Notehub
Adds a Note to a Notefile, creating the Notefile if it doesn't yet exist. The
file must either be a DB Notefile or an inbound queue file (see file
argument
below).
file
string (Default: data.qi
)
The name of the Notefile.
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
note
string (optional)
If the Notefile has a .db/.dbs
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 .qi
Notefile, an error is returned.
body
JSON object (optional)
A JSON object to be enqueued. A note must have either a body
or a payload
,
and can have both.
payload
base64 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.
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID of a Notehub project.
deviceUID
string
The globally-unique DeviceUID of a device that currently exists within the specified ProjectUID.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
curl -X POST
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>/<note>'
-H 'Authorization: Bearer <access_token>'
-d '{"body": {"temp": 72.22 }}'
Response Members
{}
means success.Delete Note Notehub
Delete Notefiles from a DB Notefile by its Note ID. To delete Notes from a
.qi
Notefile, use the Get Note
API or Get Note Changes
API with the delete:true
argument
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.
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID of a Notehub project.
deviceUID
string
The globally-unique DeviceUID of a device that currently exists within the specified ProjectUID.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
curl -X DELETE
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>/<note>'
-H 'Authorization: Bearer <access_token>'
Response Members
{}
means success.Get Note Notehub
Retrieves a Note from a DB Notefile. .qo
/.qos
Notes must be read from
the Notehub event table using the
Notehub Event API.
file
string
The Notefile must end in .db
or .dbs
.
note
string
Specifies a unique Note ID.
delete
boolean (optional)
true
to delete the Note after retrieving it, added as a URL parameter (e.g.
?delete=true
).
deleted
boolean (optional)
true
to allow retrieval of a deleted Note, added as a URL parameter (e.g.
?deleted=true
).
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID of a Notehub project.
deviceUID
string
The globally-unique DeviceUID of a device that currently exists within the specified ProjectUID.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
curl -X GET
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>/<note>'
-H 'Authorization: Bearer <access_token>'
Response Members
note
string
The Note ID.
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.
{
"note": "note-id",
"body": {
"api-key1": "api-val1"
},
"time": 1598909219
}
Get Note Changes Notehub
The Get Note Changes API is used to incrementally retrieve changes within a specific Notefile.
file
string
The Notefile ID.
tracker
string (optional)
The change tracker ID. This value is developer-defined and can be used across
both the Notecard APIs (note.changes
and file.changes
) and Notehub APIs (Get
Note Changes and Get File Changes).
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. 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*
).
delete
boolean (optional)
true
to delete the Notes returned by the request.
reset
boolean (optional)
true
to reset a change tracker.
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID of a Notehub project.
deviceUID
string
The globally-unique DeviceUID of a device that currently exists within the specified ProjectUID.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
curl -X GET
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>/changes'
-H 'Authorization: Bearer <access_token>'
curl -X GET
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>/changes?tracker=<tracker>&start=<start>&delete=<delete>&max=<max>'
-H 'Authorization: Bearer <access_token>'
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 }
}
}
Update Note Notehub
Updates a Note in a DB Notefile by its ID, replacing the existing body
and/or payload
. Inbound Notefiles may not be updated.
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.
access_token
string
A Notehub API bearer token.
projectUID
string
The ProjectUID of a Notehub project.
deviceUID
string
The globally-unique DeviceUID of a device that currently exists within the specified ProjectUID.
You may alternatively provide a device serial number by prefixing this argument
with sn:
, for example sn:my-device
.
curl -X PUT
-L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>/<note>'
-H 'Authorization: Bearer <access_token>'
-d '{"body": {"interval": 60 }}'
Response Members
{}
means success.