---
title: note Requests - API Reference
description: The note requests enable the quick creation and management of Notes in Notefiles.
source_url: https://dev.blues.io/api-reference/notecard-api/note-requests/
canonical_url: https://dev.blues.io/api-reference/notecard-api/note-requests/
markdown_url: https://dev.blues.io/api-reference/notecard-api/note-requests.md
---

# note Requests

The `note` requests enable the quick creation and management of [Notes](https://dev.blues.io/api-reference/glossary.md#note) in [Notefiles](https://dev.blues.io/api-reference/glossary.md#notefile).

The requests in this section are available on the Notecard API. Consult the [Notehub Device API](https://dev.blues.io/api-reference/notehub-api/device-api.md) to manage inbound and DB Notefiles from Notehub.

## note.add

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Adds a Note to a Notefile, creating the Notefile if it doesn't yet exist.

Arguments

### `binary`

*boolean (optional)*

If `true`, the Notecard will send all the data in the binary buffer to Notehub.

Learn more in this guide on [Sending and Receiving Large Binary Objects](https://dev.blues.io/guides-and-tutorials/notecard-guides/sending-and-receiving-large-binary-objects.md).

### `body`

*object (optional)*

A JSON object to be enqueued. A Note must have either a `body` or a `payload`, and can have both.

### `file`

*string (optional, default `data.qo`)*

The name of the Notefile.

On Notecard LoRa this argument is required. On all other Notecards this field is optional and defaults to `data.qo` if not provided.

When using this request 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

### `full`

*boolean (optional)*

If set to `true`, and the Note is using a [Notefile Template](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design.md#working-with-note-templates), the Note will bypass usage of [omitempty](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design.md#use-of-in-templates) and retain `null`, `0`, `false`, and empty string `""` values.

### `key`

*string (optional)*

The name of an environment variable in your Notehub.io project that contains the contents of a public key. Used when [encrypting the Note body for transport](https://dev.blues.io/guides-and-tutorials/notecard-guides/encrypting-and-decrypting-data-with-the-notecard.md).

### `limit`

*boolean (optional)*

If set to `true`, the Note will not be created if Notecard is in a [penalty box](https://dev.blues.io/support/understanding-notecard-penalty-boxes.md).

### `live`

*boolean (optional)*

If `true`, bypasses saving the Note to flash on the Notecard. Required to be set to `true` if also using `"binary":true`.

### `max`

*integer (optional)*

Defines the maximum number of queued Notes permitted in the specified Notefile (`"file"`). Any Notes added after this value will be rejected. When used with `"sync":true`, a sync will be triggered when the number of pending Notes matches the `max` value.

### `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"}`.

*If this argument is provided for a `.qo` Notefile, an error is returned.*

### `payload`

*string (optional)*

A base64-encoded binary payload. A Note must have either a `body` or a `payload`, and can have both. Payloads are limited to 256 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}`.

### `verify`

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

**Example**

**JSON**

```json
{
  "req": "note.add",
  "file": "sensors.qo",
  "body": {
    "temp": 72.22
  },
  "sync": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.add");
JAddStringToObject(req, "file", "sensors.qo");
J *body = JAddObjectToObject(req, "body");
JAddNumberToObject(body, "temp", 72.22);
JAddBoolToObject(req, "sync", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.add"}
req["file"] = "sensors.qo"
req["body"] = {"temp": 72.22}
req["sync"] = True
rsp = card.Transaction(req)
```

Add a Note with JSON body data and trigger immediate sync.

**Response Members**

### `note`

*string*

The generated unique Note ID when `note` parameter was set to "?".

### `template`

*boolean*

`true` when a template is active on the Notefile.

### `total`

*integer*

The total number of Notes in the Notefile.

Example Response

```json
{
  "total": 12
}
```

Related Articles

- [Encrypting and Decrypting Data with the Notecard](https://dev.blues.io/guides-and-tutorials/notecard-guides/encrypting-and-decrypting-data-with-the-notecard.md)

## note.changes

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Used to incrementally retrieve changes within a specific Notefile.

Arguments

### `delete`

*boolean (optional)*

`true` to delete the Notes returned by the request.

### `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*`).

### `file`

*string (optional)*

The Notefile ID.

### `max`

*integer (optional)*

The maximum number of Notes to return in the request.

### `reset`

*boolean (optional)*

`true` to reset a change tracker.

### `start`

*boolean (optional)*

`true` to reset the tracker to the beginning.

### `stop`

*boolean (optional)*

`true` to delete the tracker.

### `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.

**Basic File Changes**

**JSON**

```json
{
  "req": "note.changes",
  "file": "data.db"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.changes");
JAddStringToObject(req, "file", "data.db");

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.changes"}
req["file"] = "data.db"
rsp = card.Transaction(req)
```

Get changes from a Notefile without a tracker.

**Peek at Changes**

**JSON**

```json
{
  "req": "note.changes",
  "file": "my-settings.db",
  "tracker": "inbound-tracker",
  "start": true
}
```

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.changes"}
req["file"] = "my-settings.db"
req["tracker"] = "inbound-tracker"
req["start"] = True
rsp = card.Transaction(req)
```

Check changes in a Notefile with a tracker starting from the beginning.

**Pop Changes with Limit**

**JSON**

```json
{
  "req": "note.changes",
  "file": "my-settings.db",
  "tracker": "inbound-tracker",
  "start": true,
  "delete": true,
  "max": 2
}
```

**C/C++**

```cpp
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);
```

**Python**

```python
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)
```

Retrieve and delete up to 2 changes from a Notefile.

**Reset Tracker**

**JSON**

```json
{
  "req": "note.changes",
  "file": "events.db",
  "tracker": "event-tracker",
  "reset": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.changes");
JAddStringToObject(req, "file", "events.db");
JAddStringToObject(req, "tracker", "event-tracker");
JAddBoolToObject(req, "reset", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.changes"}
req["file"] = "events.db"
req["tracker"] = "event-tracker"
req["reset"] = True
rsp = card.Transaction(req)
```

Reset a change tracker to start from the beginning.

**Include Deleted Notes**

**JSON**

```json
{
  "req": "note.changes",
  "file": "config.db",
  "tracker": "config-tracker",
  "deleted": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.changes");
JAddStringToObject(req, "file", "config.db");
JAddStringToObject(req, "tracker", "config-tracker");
JAddBoolToObject(req, "deleted", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.changes"}
req["file"] = "config.db"
req["tracker"] = "config-tracker"
req["deleted"] = True
rsp = card.Transaction(req)
```

Retrieve changes including deleted notes from database.

**Stop Tracker**

**JSON**

```json
{
  "req": "note.changes",
  "file": "logs.db",
  "tracker": "log-tracker",
  "stop": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.changes");
JAddStringToObject(req, "file", "logs.db");
JAddStringToObject(req, "tracker", "log-tracker");
JAddBoolToObject(req, "stop", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.changes"}
req["file"] = "logs.db"
req["tracker"] = "log-tracker"
req["stop"] = True
rsp = card.Transaction(req)
```

Delete a change tracker when finished.

**Response Members**

### `changes`

*integer*

The number of pending changes in the Notefile.

### `notes`

*object*

An object with a key for each Note (the Note ID in a DB Notefile or an internally-generated ID for `.qo` and `.qi` Notes) and value object with the `body` of each Note and the `time` the Note was added.

### `total`

*integer*

The total number of Notes in the Notefile.

Example Response

```json
{
  "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
    }
  }
}
```

Response showing changes with Note details and timestamps.

```json
{
  "changes": 0,
  "total": 10,
  "notes": {}
}
```

Response when no changes are available.

```json
{
  "changes": 1,
  "total": 5,
  "notes": {
    "config-update": {
      "body": {
        "brightness": 75,
        "volume": 50
      },
      "time": 1609459200
    }
  }
}
```

Response with a single Note change.

Related Articles

- [Using Change Trackers With Inbound Data](https://dev.blues.io/notecard/notecard-walkthrough/inbound-requests-and-shared-data.md#using-change-trackers-with-inbound-data)

## note.delete

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Deletes a Note 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 (optional)*

The Notefile from which to delete a Note. Must be a Notefile with a `.db` or `.dbx` extension.

### `note`

*string (optional)*

The Note ID of the Note to delete.

### `verify`

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

**Delete Note from DB Notefile**

**JSON**

```json
{
  "req": "note.delete",
  "file": "my-settings.db",
  "note": "measurements"
}
```

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.delete"}
req["file"] = "my-settings.db"
req["note"] = "measurements"
rsp = card.Transaction(req)
```

Delete a specific Note by ID from a database Notefile.

**Delete Note with Verification**

**JSON**

```json
{
  "req": "note.delete",
  "file": "config.db",
  "note": "display-settings",
  "verify": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.delete");
JAddStringToObject(req, "file", "config.db");
JAddStringToObject(req, "note", "display-settings");
JAddBoolToObject(req, "verify", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.delete"}
req["file"] = "config.db"
req["note"] = "display-settings"
req["verify"] = True
rsp = card.Transaction(req)
```

Delete a Note and write to flash immediately for a templated Notefile.

**Delete Note with Command**

**JSON**

```json
{
  "cmd": "note.delete",
  "file": "temp-data.db",
  "note": "sensor-reading"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.delete");
JAddStringToObject(req, "file", "temp-data.db");
JAddStringToObject(req, "note", "sensor-reading");

NoteRequest(req);
```

**Python**

```python
req = {"cmd": "note.delete"}
req["file"] = "temp-data.db"
req["note"] = "sensor-reading"
card.Transaction(req)
```

Delete a Note using command syntax (no response expected).

**Response Members**

None: an empty object `{}` means success.

Related Articles

- [Deleting Notes from a DB Notefile](https://dev.blues.io/notecard/notecard-walkthrough/inbound-requests-and-shared-data.md#deleting-notes-from-a-db-notefile)
- [Storing Structured State with note Requests](https://dev.blues.io/guides-and-tutorials/notecard-guides/storing-device-state-with-db-notefiles.md#storing-structured-state-with-note-requests)

## note.get

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

Retrieves a Note from a Notefile. The file must either be a DB Notefile or inbound queue file (see `file` argument below).

`.qo`/`.qos` Notes must be read from the Notehub event table using the [Notehub Event API](https://dev.blues.io/api-reference/notehub-api/event-api.md).

Arguments

### `decrypt`

*boolean (optional)*

`true` to decrypt [encrypted inbound Notefiles](https://dev.blues.io/guides-and-tutorials/notecard-guides/encrypting-and-decrypting-data-with-the-notecard.md).

### `delete`

*boolean (optional)*

`true` to delete the Note after retrieving it.

### `deleted`

*boolean (optional)*

`true` to allow retrieval of a deleted Note.

### `file`

*string (optional, default `data.qi`)*

The Notefile name must end in `.qi` (for plaintext transport), `.qis` (for encrypted transport), `.db` or `.dbx` (for local-only DB Notefiles).

### `note`

*string (optional)*

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

**Pop from \`.qi\` Notefile**

**JSON**

```json
{
  "req": "note.get",
  "file": "requests.qi",
  "delete": true
}
```

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.get"}
req["file"] = "requests.qi"
req["delete"] = True
rsp = card.Transaction(req)
```

Retrieve and delete a Note from an inbound queue file.

**Read from \`.db\` Notefile**

**JSON**

```json
{
  "req": "note.get",
  "file": "my-settings.db",
  "note": "measurements"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.get");
JAddStringToObject(req, "file", "my-settings.db");
JAddStringToObject(req, "note", "measurements");

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.get"}
req["file"] = "my-settings.db"
req["note"] = "measurements"
rsp = card.Transaction(req)
```

Read a specific Note from a database Notefile.

**Get with Default File**

**JSON**

```json
{
  "req": "note.get"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.get");

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.get"}
rsp = card.Transaction(req)
```

Retrieve from the default `data.qi` Notefile.

**Get Deleted Note**

**JSON**

```json
{
  "req": "note.get",
  "file": "config.db",
  "note": "old-setting",
  "deleted": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.get");
JAddStringToObject(req, "file", "config.db");
JAddStringToObject(req, "note", "old-setting");
JAddBoolToObject(req, "deleted", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.get"}
req["file"] = "config.db"
req["note"] = "old-setting"
req["deleted"] = True
rsp = card.Transaction(req)
```

Retrieve a deleted Note from a `.db` Notefile.

**Decrypt Encrypted Note**

**JSON**

```json
{
  "req": "note.get",
  "file": "secure.qis",
  "decrypt": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.get");
JAddStringToObject(req, "file", "secure.qis");
JAddBoolToObject(req, "decrypt", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.get"}
req["file"] = "secure.qis"
req["decrypt"] = True
rsp = card.Transaction(req)
```

Retrieve and decrypt an encrypted inbound Note.

**Response Members**

### `body`

*object*

The JSON body, if contained in the Note.

### `payload`

*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

```json
{
  "body": {
    "api-key1": "api-val1"
  },
  "time": 1598909219
}
```

Related Articles

- [Handling Inbound Notes](https://dev.blues.io/notecard/notecard-walkthrough/inbound-requests-and-shared-data.md#handling-inbound-notes)
- [Receiving Commands on a Device](https://dev.blues.io/guides-and-tutorials/notecard-guides/remote-command-and-control.md#receiving-commands-on-a-device)

## note.template

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

By using the `note.template` request 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](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design.md#working-with-note-templates) for additional information.

Arguments

### `body`

*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](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design.md#understanding-template-data-types) for an explanation of type hints and explanations.

### `delete`

*boolean (optional)*

Set to `true` to delete all pending Notes using the template if one of the following scenarios is also true:

Connecting via non-NTN (e.g. cellular or WiFi) communications, but attempting to sync NTN-compatible Notefiles.

or

Connecting via NTN (e.g. satellite) communications, but attempting to sync non-NTN-compatible Notefiles.

Read more about this feature in [Starnote Best Practices](https://dev.blues.io/starnote/satellite-best-practices.md#define-ntn-vs-non-ntn-templates).

### `file`

*string (optional)*

The name of the Notefile to which the template will be applied.

### `format`

*string (optional)*

By default all Note templates automatically include metadata, including a timestamp for when the Note was created, various fields about a device's location, as well as a timestamp for when the device's location was determined.

By providing a `format` of `"compact"` you tell the Notecard to omit this additional metadata to save on storage and bandwidth. The use of `format: "compact"` is required for Notecard LoRa and a Notecard paired with Starnote.

When using `"compact"` templates, you may include the following keywords in your template to add in fields that would otherwise be omitted: `_lat`, `_lon`, `_ltime`, `_time`. See [Creating Compact Templates](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design.md#creating-compact-templates) to learn more.

### `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 not required, and payloads can be added to any template-based Note without specifying the payload length.

### `port`

*integer (optional)*

This argument is required on Notecard LoRa and a Notecard paired with Starnote, but ignored on all other Notecards.

A port is a unique integer in the range 1–100, where each unique number represents one Notefile. This argument allows the Notecard to send a numerical reference to the Notefile over the air, rather than the full Notefile name.

The port you provide is also used in the "frame port" field on LoRaWAN gateways.

### `verify`

*boolean (optional)*

If `true`, returns the current template set on a given Notefile.

**Provide Schema**

**JSON**

```json
{
  "req": "note.template",
  "file": "readings.qo",
  "body": {
    "new_vals": true,
    "temperature": 14.1,
    "humidity": 11,
    "pump_state": "4"
  }
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.template");
JAddStringToObject(req, "file", "readings.qo");
J *body = JAddObjectToObject(req, "body");
JAddBoolToObject(body, "new_vals", true);
JAddNumberToObject(body, "temperature", 14.1);
JAddNumberToObject(body, "humidity", 11);
JAddStringToObject(body, "pump_state", "4");

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.template"}
req["file"] = "readings.qo"
req["body"] = {"new_vals": true, "temperature": 14.1, "humidity": 11, "pump_state": "4"}
rsp = card.Transaction(req)
```

Provide a template schema for the readings.qo Notefile with sample data.

**Compact Schema for LoRa**

**JSON**

```json
{
  "req": "note.template",
  "file": "readings.qo",
  "body": {
    "new_vals": true,
    "temperature": 14.1,
    "humidity": 11,
    "pump_state": "4"
  },
  "format": "compact",
  "port": 50
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.template");
JAddStringToObject(req, "file", "readings.qo");
J *body = JAddObjectToObject(req, "body");
JAddBoolToObject(body, "new_vals", true);
JAddNumberToObject(body, "temperature", 14.1);
JAddNumberToObject(body, "humidity", 11);
JAddStringToObject(body, "pump_state", "4");
JAddStringToObject(req, "format", "compact");
JAddNumberToObject(req, "port", 50);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.template"}
req["file"] = "readings.qo"
req["body"] = {"new_vals": true, "temperature": 14.1, "humidity": 11, "pump_state": "4"}
req["format"] = "compact"
req["port"] = 50
rsp = card.Transaction(req)
```

Set up a compact template for LoRa transmission on port 50 to reduce bandwidth usage.

**Compact Schema with Additional Fields**

**JSON**

```json
{
  "req": "note.template",
  "file": "readings.qo",
  "body": {
    "temperature": 14.1,
    "_lat": 14.1,
    "_lon": 14.1,
    "_ltime": 14,
    "_time": 14
  },
  "format": "compact",
  "port": 50
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.template");
JAddStringToObject(req, "file", "readings.qo");
J *body = JAddObjectToObject(req, "body");
JAddNumberToObject(body, "temperature", 14.1);
JAddNumberToObject(body, "_lat", 14.1);
JAddNumberToObject(body, "_lon", 14.1);
JAddNumberToObject(body, "_ltime", 14);
JAddNumberToObject(body, "_time", 14);
JAddStringToObject(req, "format", "compact");
JAddNumberToObject(req, "port", 50);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.template"}
req["file"] = "readings.qo"
req["body"] = {"temperature": 14.1, "_lat": 14.1, "_lon": 14.1, "_ltime": 14, "_time": 14}
req["format"] = "compact"
req["port"] = 50
rsp = card.Transaction(req)
```

Set up a compact template including location and timestamp fields for comprehensive sensor data.

**Request Current Template**

**JSON**

```json
{
  "req": "note.template",
  "file": "readings.qo",
  "verify": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.template");
JAddStringToObject(req, "file", "readings.qo");
JAddBoolToObject(req, "verify", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.template"}
req["file"] = "readings.qo"
req["verify"] = True
rsp = card.Transaction(req)
```

Retrieve the current template configuration for the readings.qo Notefile.

**Clear Template**

**JSON**

```json
{
  "req": "note.template",
  "file": "readings.qo"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.template");
JAddStringToObject(req, "file", "readings.qo");

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.template"}
req["file"] = "readings.qo"
rsp = card.Transaction(req)
```

Clear the template from readings.qo. Omitting `body` and `payload` removes the template schema; subsequent Notes added to the Notefile will be stored as regular JSON objects.

**Response Members**

### `body`

*object*

If the `verify` argument is provided and the Notefile has an active template, the template `body`.

### `bytes`

*integer*

The number of bytes that will be transmitted to Notehub, per Note, before compression.

### `delete`

*boolean*

If the `verify` argument is provided, `true` when the template was created with `delete` set to `true`. Omitted otherwise.

### `format`

*string*

If the `format` argument is provided, this represents the format applied to the template.

### `length`

*integer*

If the `verify` argument is provided and the Notefile has an active template with a payload, the payload length.

### `port`

*integer*

If the `verify` argument is provided and the Notefile has an active template, the `port` assigned to the template.

### `template`

*boolean*

`true` if an active template exists on the Notefile.

Example Response

```json
{
  "bytes": 40
}
```

Response when template is successfully set, showing bytes per note.

```json
{
  "template": true,
  "body": {
    "temperature": 14.1,
    "humidity": 11
  },
  "bytes": 40
}
```

Response when verifying existing template with all fields.

```json
{
  "template": true,
  "format": "compact",
  "bytes": 25
}
```

Response showing compact format template.

Related Articles

- [Working With Note Templates](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design.md#working-with-note-templates)
- [Understanding Template Data Types](https://dev.blues.io/notecard/notecard-walkthrough/low-bandwidth-design.md#understanding-template-data-types)

## note.update

Supported on

(Cell, Cell+WiFi, LoRa, Skylo, WiFi)

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

Arguments

### `body`

*object (optional)*

A JSON object to add to the Note. A Note must have either a `body` or `payload`, and can have both.

### `file`

*string (optional)*

The name of the DB Notefile that contains the Note to update.

### `note`

*string (optional)*

The unique Note ID.

### `payload`

*string (optional)*

A base64-encoded binary payload. A Note must have either a `body` or `payload`, and can have both.

### `sync`

*boolean (optional)*

Set to `true` to sync the Notefile immediately after updating the Note. Only the specified Notefile is guaranteed to sync.

### `verify`

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

**Update Note Body**

**JSON**

```json
{
  "req": "note.update",
  "file": "my-settings.db",
  "note": "measurements",
  "body": {
    "interval": 60
  }
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "my-settings.db");
JAddStringToObject(req, "note", "measurements");
J *body = JAddObjectToObject(req, "body");
JAddNumberToObject(body, "interval", 60);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.update"}
req["file"] = "my-settings.db"
req["note"] = "measurements"
req["body"] = {"interval": 60}
rsp = card.Transaction(req)
```

Update a Note with new JSON body content.

**Update Note Payload**

**JSON**

```json
{
  "req": "note.update",
  "file": "data.db",
  "note": "sensor-1",
  "payload": "SGVsbG8gV29ybGQ="
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "data.db");
JAddStringToObject(req, "note", "sensor-1");
JAddStringToObject(req, "payload", "SGVsbG8gV29ybGQ=");

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.update"}
req["file"] = "data.db"
req["note"] = "sensor-1"
req["payload"] = "SGVsbG8gV29ybGQ="
rsp = card.Transaction(req)
```

Update a Note with new base64 payload data.

**Update with Body and Payload**

**JSON**

```json
{
  "req": "note.update",
  "file": "config.db",
  "note": "device-config",
  "body": {
    "enabled": true
  },
  "payload": "YWRkaXRpb25hbERhdGE="
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "config.db");
JAddStringToObject(req, "note", "device-config");
J *body = JAddObjectToObject(req, "body");
JAddBoolToObject(body, "enabled", true);
JAddStringToObject(req, "payload", "YWRkaXRpb25hbERhdGE=");

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.update"}
req["file"] = "config.db"
req["note"] = "device-config"
req["body"] = {"enabled": true}
req["payload"] = "YWRkaXRpb25hbERhdGE="
rsp = card.Transaction(req)
```

Update a Note with both body and payload.

**Update with Verification**

**JSON**

```json
{
  "req": "note.update",
  "file": "template.db",
  "note": "user-setting",
  "body": {
    "theme": "dark"
  },
  "verify": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "template.db");
JAddStringToObject(req, "note", "user-setting");
J *body = JAddObjectToObject(req, "body");
JAddStringToObject(body, "theme", "dark");
JAddBoolToObject(req, "verify", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.update"}
req["file"] = "template.db"
req["note"] = "user-setting"
req["body"] = {"theme": "dark"}
req["verify"] = True
rsp = card.Transaction(req)
```

Update a Note in a templated Notefile with immediate flash write.

**Update with Command**

**JSON**

```json
{
  "cmd": "note.update",
  "file": "cache.db",
  "note": "temp-data",
  "body": {
    "status": "updated"
  }
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "cache.db");
JAddStringToObject(req, "note", "temp-data");
J *body = JAddObjectToObject(req, "body");
JAddStringToObject(body, "status", "updated");

NoteRequest(req);
```

**Python**

```python
req = {"cmd": "note.update"}
req["file"] = "cache.db"
req["note"] = "temp-data"
req["body"] = {"status": "updated"}
card.Transaction(req)
```

Update a Note using command syntax (no response expected).

**Update and Sync**

**JSON**

```json
{
  "req": "note.update",
  "file": "my-settings.db",
  "note": "measurements",
  "body": {
    "interval": 60
  },
  "sync": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("note.update");
JAddStringToObject(req, "file", "my-settings.db");
JAddStringToObject(req, "note", "measurements");
J *body = JAddObjectToObject(req, "body");
JAddNumberToObject(body, "interval", 60);
JAddBoolToObject(req, "sync", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "note.update"}
req["file"] = "my-settings.db"
req["note"] = "measurements"
req["body"] = {"interval": 60}
req["sync"] = True
rsp = card.Transaction(req)
```

Update a Note and trigger an immediate sync of the Notefile.

**Response Members**

None: an empty object `{}` means success.

Related Articles

- [Storing Structured State with note Requests](https://dev.blues.io/guides-and-tutorials/notecard-guides/storing-device-state-with-db-notefiles.md#storing-structured-state-with-note-requests)
- [Adding and Updating Notes in DB Notefiles](https://dev.blues.io/notecard/notecard-walkthrough/inbound-requests-and-shared-data.md#adding-and-updating-notes-in-db-notefiles)

[hub Requests](https://dev.blues.io/api-reference/notecard-api/hub-requests.md "hub Requests") [ntn Requests](https://dev.blues.io/api-reference/notecard-api/ntn-requests.md "ntn Requests")