homechevron_rightDocschevron_rightAPI Referencechevron_rightNotecard APIchevron_rightfile Requests - API Reference

file Requests

The file set of requests enable developers to work with all types of Notefiles.

The requests in this section are available on the Notecard API. Consult the Notehub Device API to manage inbound and DB Notefiles from Notehub.

Notecard Firmware Version:

file.changes CellCell+WiFiLoRaWiFi

Used to perform queries on a single or multiple files to determine if new Notes are available to read, or if there are unsynced Notes in local Notefiles.

Note: This request is a Notefile API request, only. .qo Notes in Notehub are automatically ingested and stored, or sent to applicable Routes.

Arguments

`files`

array of string (optional)

One or more files to obtain change information from. Omit to return changes for all Notefiles.

`tracker`

string (optional)

Cell Cell+WiFi WiFi

ID of a change tracker to use to determine changes to Notefiles.

Check All Files

JSON

{
  "req": "file.changes"
}

C/C++

J *req = NoteNewRequest("file.changes");

NoteRequest(req);

Python

req = {"req": "file.changes"}
rsp = card.Transaction(req)

Check all Notefiles for changes without specifying files or tracker.

Check Specific Files

JSON

{
  "req": "file.changes",
  "files": [
    "sensors.qo",
    "data.qo"
  ]
}

C/C++

J *req = NoteNewRequest("file.changes");
J *files = JAddArrayToObject(req, "files");
JAddItemToArray(files, JCreateString("sensors.qo"));
JAddItemToArray(files, JCreateString("data.qo"));

NoteRequest(req);

Python

req = {"req": "file.changes"}
req["files"] = ["sensors.qo", "data.qo"]
rsp = card.Transaction(req)

Check specific Notefiles for changes.

Use Change Tracker

JSON

{
  "req": "file.changes",
  "tracker": "my-tracker"
}

C/C++

J *req = NoteNewRequest("file.changes");
JAddStringToObject(req, "tracker", "my-tracker");

NoteRequest(req);

Python

req = {"req": "file.changes"}
req["tracker"] = "my-tracker"
rsp = card.Transaction(req)

Use a change tracker to monitor file changes over time.

Tracker with Specific Files

JSON

{
  "req": "file.changes",
  "files": [
    "sensors.qo"
  ],
  "tracker": "sensor-tracker"
}

C/C++

J *req = NoteNewRequest("file.changes");
J *files = JAddArrayToObject(req, "files");
JAddItemToArray(files, JCreateString("sensors.qo"));
JAddStringToObject(req, "tracker", "sensor-tracker");

NoteRequest(req);

Python

req = {"req": "file.changes"}
req["files"] = ["sensors.qo"]
req["tracker"] = "sensor-tracker"
rsp = card.Transaction(req)

Combine change tracker with specific file monitoring.

Response Members

`changes`

integer

If a change tracker is used, the number of changes across all files.

`info`

object

An object with a key for each Notefile that matched the request parameters, and value object with the changes and total for each file.

`pending`

boolean

Set to true if this was a pending changes request and there are changes

`total`

integer

The total of local Notes across all Notefiles. This includes Inbound Notes that have not been deleted, as well as outbound Notes that have yet to sync.

Example Response

{
  "changes": 5,
  "total": 5,
  "info": {
    "my-settings.db": {
      "changes": 3,
      "total": 3
    },
    "other-settings.db": {
      "changes": 2,
      "total": 2
    }
  }
}

file.changes.pending CellCell+WiFiLoRaWiFi

Returns info about file changes that are pending upload to Notehub.

Arguments

None

Example

JSON

{
  "req": "file.changes.pending"
}

C/C++

J *req = NoteNewRequest("file.changes.pending");

NoteRequest(req);

Python

req = {"req": "file.changes.pending"}
rsp = card.Transaction(req)

Query for pending file changes awaiting upload to Notehub.

Response Members

`changes`

integer

The number of changes across all files.

`info`

object

An object with a key for each Notefile and value object with the changes and total for each file.

`pending`

boolean

true if there are pending changes.

`total`

integer

The total of unsynced notes across all Notefiles.

Example Response

{
  "total": 3,
  "changes": 3,
  "pending": true,
  "info": {
    "sensors.qo": {
      "changes": 3,
      "total": 3
    }
  }
}

Response showing pending changes across multiple files.

{
  "total": 0,
  "changes": 0,
  "pending": false
}

Response when no changes are pending upload.

{
  "total": 5,
  "changes": 5,
  "pending": true,
  "info": {
    "sensors.qo": {
      "changes": 3,
      "total": 3
    },
    "data.qo": {
      "changes": 2,
      "total": 2
    }
  }
}

Response with pending changes across multiple Notefiles.

file.clear CellCell+WiFiWiFi

note

This request is not available in the currently selected Notecard firmware version.

file.delete CellCell+WiFiLoRaWiFi

Deletes Notefiles and the Notes they contain.

Arguments

`files`

array of string

One or more files to delete.

Delete Multiple Files

JSON

{
  "req": "file.delete",
  "files": [
    "my-settings.db",
    "other-settings.db"
  ]
}

C/C++

J *req = NoteNewRequest("file.delete");
J *files = JAddArrayToObject(req, "files");
JAddItemToArray(files, JCreateString("my-settings.db"));
JAddItemToArray(files, JCreateString("other-settings.db"));

NoteRequest(req);

Python

req = {"req": "file.delete"}
req["files"] = ["my-settings.db", "other-settings.db"]
rsp = card.Transaction(req)

Delete multiple Notefiles and their contents.

Delete Single File

JSON

{
  "req": "file.delete",
  "files": [
    "data.qo"
  ]
}

C/C++

J *req = NoteNewRequest("file.delete");
J *files = JAddArrayToObject(req, "files");
JAddItemToArray(files, JCreateString("data.qo"));

NoteRequest(req);

Python

req = {"req": "file.delete"}
req["files"] = ["data.qo"]
rsp = card.Transaction(req)

Delete a single Notefile and its contents.

Response Members

None: an empty object {} means success.

file.stats CellCell+WiFiLoRaWiFi

Gets resource statistics about local Notefiles.

Arguments

`file`

string (optional)

Returns the stats for the specified Notefile only.

Get All File Stats

JSON

{
  "req": "file.stats"
}

C/C++

J *req = NoteNewRequest("file.stats");

NoteRequest(req);

Python

req = {"req": "file.stats"}
rsp = card.Transaction(req)

Get resource statistics for all Notefiles.

Get Specific File Stats

JSON

{
  "req": "file.stats",
  "file": "sensors.qo"
}

C/C++

J *req = NoteNewRequest("file.stats");
JAddStringToObject(req, "file", "sensors.qo");

NoteRequest(req);

Python

req = {"req": "file.stats"}
req["file"] = "sensors.qo"
rsp = card.Transaction(req)

Get resource statistics for a specific Notefile.

Response Members

`changes`

integer

The number of Notes across all Notefiles pending sync.

`sync`

boolean

true if a sync is recommended based on the number of pending notes.

`total`

integer

The total number of Notes across all Notefiles.

Example Response

{
  "total": 83,
  "changes": 78,
  "sync": true
}

Response with resource statistics showing pending sync recommendation.

{
  "total": 25,
  "changes": 0,
  "sync": false
}

Response when no changes are pending sync.

env Requests hub Requests