Support
Blues.io
Notehub.io
Shop
Support
Blues.io
Notehub.io
Shop
×
HomeReference
Glossary
Notecard Walkthrough
Overview
Notecard Requests & Responses
JSON Fundamentals
Notecard Interfaces
Essential Requests
Time & Location Requests
Inbound Requests & Shared Data
Web Transactions
Low Power Design
Low Bandwidth Design
Host Firmware Update Requests
Advanced Notecard Configuration
Complete API Reference
Introduction
card Requests
dfu Requests
env Requests
file Requests
hub Requests
note Requestsnote.addnote.changesnote.deletenote.getnote.updatenote.template
web Requests

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 (.qo/.qos). When sending this request to Notehub, the file must either be a DB Notefile or an inbound queue file (.qi/.qis).

Arguments

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

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}

    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 }

    note.changes

    Used to incrementally retrieve changes within a specific Notefile.

    Arguments

    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.

      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:
      • Using Change Trackers With Inbound Data

      note.delete

      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.

      Arguments

      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
        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 (.db) or inbound queue file (.qi/.qis). When sending this request to Notehub, the file must be a DB Notefile (.db). .qo/.qo Notes must be read from the Notehub event table using a hub.app.data.query request.

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

          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.

            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.

            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)

            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.

              Example Response
              {
                "bytes": 40
              }
              
              More information:
              • Working With Note Templates

              • Understanding Template Data Types

              hub Requestsweb Requests
              Can we improve this page? Send us feedbackRate this page
              • ★
                ★
              • ★
                ★
              • ★
                ★
              • ★
                ★
              • ★
                ★
              © 2021 Blues Inc.Terms & ConditionsPrivacy
              blues.ioTwitterLinkedInGitHubHackster.io
              Disconnected
              Disconnected
              Having trouble connecting?

              Try changing your Micro USB cable as some cables do not support transferring data. If that does not solve your problem, contact us at support@blues.com and we will get you set up with another tool to communicate with the Notecard.

              Connect a NotecardClick 'Connect' and select a USB-connected Notecard to start issuing requests from the browser.