note Requests

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.

note.add

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 (see file argument below).
  • When sending this request to Notehub, the file must either be a DB Notefile or an inbound queue file (see file argument below).
Arguments

file

string (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

note

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

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.

sync

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

access_token

string (Notehub curl requests only)

A Notehub API bearer token.

projectUID

string (Notehub curl requests only)

The ProjectUID of a Notehub project.

deviceUID

string (Notehub curl requests only)

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.

      {
  "req": "note.add",
  "file": "sensors.qo",
  "body": { "temp": 72.22 },
  "sync": true
}
      J *req = NoteNewRequest("note.add");
JAddStringToObject(req, "file", "sensors.qo");
JAddBoolToObject(req, "sync", true);

J *body = JCreateObject();
JAddNumberToObject(body, "temp", 72.22);
JAddItemToObject(req, "body", body);

NoteRequest(req);
      req = {"req": "note.add"}
req["file"] = "sensors.qo"
req["body"] = {"temp": 72.22 }
req["sync"] = True
rsp = card.Transaction(req)
      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

      total

      The total number of Notes in the Notefile.

      template

      true when a template is active on the Notefile.

      Example Response
      { "total": 12 }
      More information:

      note.changes

      Used to incrementally retrieve changes within a specific Notefile.

      Arguments

      file

      string

      The Notefile ID.

      tracker

      string (optional)

      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. 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 (Notehub curl requests only)

      A Notehub API bearer token.

      projectUID

      string (Notehub curl requests only)

      The ProjectUID of a Notehub project.

      deviceUID

      string (Notehub curl requests only)

      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.

          {
  "req": "note.changes",
  "file": "my-settings.db",
  "tracker": "inbound-tracker",
  "start": true
}
          J *req = NoteNewRequest("note.changes");
JAddStringToObject(req, "file", "my-settings.db");
JAddStringToObject(req, "tracker", "inbound-tracker");
JAddBoolToObject(req, "start", true);

NoteRequest(req);
          req = {"req": "note.changes"}
req["file"] = "my-settings.db"
req["tracker"] = "inbound-tracker"
req["start"] = True
rsp = card.Transaction(req)
          curl -X GET
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>/changes'
     -H 'Authorization: Bearer <access_token>'
            {
  "req": "note.changes",
  "file": "my-settings.db",
  "tracker": "inbound-tracker",
  "start": true,
  "delete": true,
  "max": 2
}
            J *req = NoteNewRequest("note.changes");
JAddStringToObject(req, "file", "my-settings.db");
JAddStringToObject(req, "tracker", "inbound-tracker");
JAddBoolToObject(req, "start", true);
JAddBoolToObject(req, "delete", true);
JAddNumberToObject(req, "max", 2);

NoteRequest(req);
            req = {"req": "note.changes"}
req["file"] = "my-settings.db"
req["tracker"] = "inbound-tracker"
req["start"] = True
req["delete"] = True
req["max"] = 2
rsp = card.Transaction(req)
            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.

            Example Response
            {
  "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 }
  }
}
            More information:

            note.delete

            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.

            Arguments

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

            access_token

            string (Notehub curl requests only)

            A Notehub API bearer token.

            projectUID

            string (Notehub curl requests only)

            The ProjectUID of a Notehub project.

            deviceUID

            string (Notehub curl requests only)

            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.

                {
  "req": "note.delete",
  "file": "my-settings.db",
  "note": "measurements"
}
                J *req = NoteNewRequest("note.delete");
JAddStringToObject(req, "file", "my-settings.db");
JAddStringToObject(req, "note", "measurements");

NoteRequest(req);
                req = {"req": "note.delete"}
req["file"] = "my-settings.db"
req["note"] = "measurements"
card.Transaction(req)
                curl -X DELETE
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>/<note>'
     -H 'Authorization: Bearer <access_token>'
                Response Members
                None: an empty object {} means success.

                note.get

                Retrieves a Note from a Notefile.

                • When sending this request to the Notecard, the file must either be a DB Notefile or inbound queue file (see file argument below).
                • When sending this request to Notehub, the file must be a DB Notefile (see file argument below).

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

                Arguments

                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), .db or .dbx (for local-only Database Notefiles).

                On Notehub, the Notefile must end in .db.

                note

                string (optional)

                If the Notefile has a .db or .dbx extension, specifies a unique Note ID. Not applicable to .qi and .qo Notefiles.

                delete

                boolean (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).

                deleted

                boolean (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).

                access_token

                string (Notehub curl requests only)

                A Notehub API bearer token.

                projectUID

                string (Notehub curl requests only)

                The ProjectUID of a Notehub project.

                deviceUID

                string (Notehub curl requests only)

                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.

                    {
  "req": "note.get",
  "file": "requests.qi",
  "delete": true
}
                    J *req = NoteNewRequest("note.get");
JAddStringToObject(req, "file", "requests.qi");
JAddBoolToObject(req, "delete", true);

NoteRequest(req);
                    req = {"req": "note.get"}
req["file"] = "requests.qi"
req["delete"] = True
rsp = card.Transaction(req)
                      {
  "req": "note.get",
  "file": "my-settings.db",
  "note": "measurements"
}
                      J *req = NoteNewRequest("note.get");
JAddStringToObject(req, "file", "my-settings.db");
JAddStringToObject(req, "note", "measurements");

NoteRequest(req);
                      req = {"req": "note.get"}
req["file"] = "my-settings.db"
req["note"] = "measurements"
rsp = card.Transaction(req)
                      curl -X GET
     -L 'https://api.notefile.net/v1/projects/<projectUID>/devices/<deviceUID>/notes/<file>/<note>'
     -H 'Authorization: Bearer <access_token>'
                      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.

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

                      note.update

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

                      Arguments

                      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.

                      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.

                      access_token

                      string (Notehub curl requests only)

                      A Notehub API bearer token.

                      projectUID

                      string (Notehub curl requests only)

                      The ProjectUID of a Notehub project.

                      deviceUID

                      string (Notehub curl requests only)

                      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.

                          {
  "req": "note.update",
  "file": "my-settings.db",
  "note": "measurements",
  "body": { "interval": 60 }
}
                          J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "my-settings.db");
JAddStringToObject(req, "note", "measurements");

J *body = JCreateObject();
JAddNumberToObject(body, "interval", 60);
JAddItemToObject(req, "body", body);

NoteRequest(req);
                          req = {"req": "note.update"}
req["file"] = "my-settings.db"
req["note"] = "measurements"
req["body"] = {"interval": 60 }
card.Transaction(req)
                          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
                          None: an empty object {} means success.

                          note.template

                          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.

                          Arguments

                          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)

                          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.

                              {
  "req": "note.template",
  "file": "readings.qo",
  "body": {
    "new_vals": true,
    "temperature": 12.1,
    "humidity": 11,
    "pump_state": "4"
  },
  "length": 32
}
                              J *req = NoteNewRequest("note.template");
JAddStringToObject(req, "file", "readings.qo");
JAddNumberToObject(req, "length", 32);

J *body = JCreateObject();
JAddBoolToObject(body, "new_vals", true);
JAddNumberToObject(body, "temperature", 12.1);
JAddNumberToObject(body, "humidity", 11);
JAddStringToObject(body, "pump_state", "4");
JAddItemToObject(req, "body", body);

NoteRequest(req);
                              req = {"req": "note.template"}
req["file"] = "readings.qo"
req["body"] = {
    "new_vals": True,
    "temperature": 12.1,
    "humidity": 11,
    "pump_state": "4"
  }
req["length"] = 32
rsp = card.Transaction(req)
                                {
  "req": "note.template",
  "file": "readings.qo"
}
                                J *req = NoteNewRequest("note.template");
JAddStringToObject(req, "file", "readings.qo");

NoteRequest(req);
                                req = {"req": "note.template"}
req["file"] = "readings.qo"
rsp = card.Transaction(req)
                                  {
  "req":    "note.template",
  "file":   "readings.qo",
  "verify": true
}
                                  J *req = NoteNewRequest("note.template");
JAddStringToObject(req, "file", "readings.qo");
JAddBoolToObject(req, "verify", true);

NoteRequest(req);
                                  req = {"req": "note.template"}
req["file"] = "readings.qo"
req["verify"] = True
rsp = card.Transaction(req)
                                  Response Members

                                  bytes

                                  integer

                                  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.

                                  Example Response
                                  {
  "bytes": 40
}
                                  More information: