---
title: file Requests - API Reference - 4.x LTS
description: The file set of requests enable developers to work with all types of Notefiles.
source_url: https://dev.blues.io/api-reference/notecard-api/file-requests/4-x-lts/
canonical_url: https://dev.blues.io/api-reference/notecard-api/file-requests/latest/
markdown_url: https://dev.blues.io/api-reference/notecard-api/file-requests/4-x-lts.md
---

# 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](https://dev.blues.io/api-reference/notehub-api/device-api.md) to manage inbound and DB Notefiles from Notehub.

## file.changes {#file-changes}

Supported on

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

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` {#file-changes--files}

*array of string (optional)*

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

### `tracker` {#file-changes--tracker}

*string (optional)*

(Cell)  (Cell+WiFi)  (Skylo)  (WiFi)

ID of a [change tracker](https://dev.blues.io/notecard/notecard-walkthrough/inbound-requests-and-shared-data.md#using-change-trackers-with-inbound-data) to use to determine changes to Notefiles. Must be accompanied by a `files` argument.

**Check All Files**

**JSON**

```json
{
  "req": "file.changes"
}
```

**C/C++**

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

NoteRequest(req);
```

**Python**

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

Check all Notefiles for changes without specifying files or tracker.

**Check Specific Files**

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

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

Check specific Notefiles for changes.

**Tracker with Specific Files**

**JSON**

```json
{
  "req": "file.changes",
  "files": [
    "commands.qi"
  ],
  "tracker": "command-tracker"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("file.changes");
J *files = JAddArrayToObject(req, "files");
JAddItemToArray(files, JCreateString("commands.qi"));
JAddStringToObject(req, "tracker", "command-tracker");

NoteRequest(req);
```

**Python**

```python
req = {"req": "file.changes"}
req["files"] = ["commands.qi"]
req["tracker"] = "command-tracker"
rsp = card.Transaction(req)
```

Use a change tracker to monitor an inbound Notefile over time. Each call reports only the Notes added since the previous call that used the same tracker ID.

**Tracker with Multiple Files**

**JSON**

```json
{
  "req": "file.changes",
  "files": [
    "commands.qi",
    "my-settings.db"
  ],
  "tracker": "my-tracker"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("file.changes");
J *files = JAddArrayToObject(req, "files");
JAddItemToArray(files, JCreateString("commands.qi"));
JAddItemToArray(files, JCreateString("my-settings.db"));
JAddStringToObject(req, "tracker", "my-tracker");

NoteRequest(req);
```

**Python**

```python
req = {"req": "file.changes"}
req["files"] = ["commands.qi", "my-settings.db"]
req["tracker"] = "my-tracker"
rsp = card.Transaction(req)
```

A single tracker ID can span multiple Notefiles.

**Response Members**

### `changes` {#file-changes--changes}

*integer*

The number of changes across all files. Omitted when the request did not supply a `tracker`, and omitted when the count is zero.

### `info` {#file-changes--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` {#file-changes--pending}

*boolean*

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

### `total` {#file-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

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

Related Articles

- [Handling Inbound Notes](https://dev.blues.io/notecard/notecard-walkthrough/inbound-requests-and-shared-data.md#handling-inbound-notes)
- [Using a Change Tracker Across Notefiles](https://dev.blues.io/notecard/notecard-walkthrough/inbound-requests-and-shared-data.md#using-change-trackers-across-multiple-notefiles)

## file.changes.pending {#file-changes-pending}

Supported on

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

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

Arguments

### `files` {#file-changes-pending--files}

*array of string (optional)*

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

**Check Pending Changes**

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

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

Query for pending file changes awaiting upload to Notehub.

**Check Pending Changes for Specific Files**

**JSON**

```json
{
  "req": "file.changes.pending",
  "files": [
    "sensors.qo"
  ]
}
```

**C/C++**

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

NoteRequest(req);
```

**Python**

```python
req = {"req": "file.changes.pending"}
req["files"] = ["sensors.qo"]
rsp = card.Transaction(req)
```

Limit the response to the specified Notefiles.

**Response Members**

### `changes` {#file-changes-pending--changes}

*integer*

The number of changes across all files.

### `info` {#file-changes-pending--info}

*object*

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

### `pending` {#file-changes-pending--pending}

*boolean*

`true` if there are pending changes.

### `total` {#file-changes-pending--total}

*integer*

The total number of local Notes across all Notefiles that matched the request.

Example Response

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

Response showing pending changes across multiple files.

```json
{}
```

Response when no changes are pending upload.

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

Related Articles

- [Miscellaneous File Requests](https://dev.blues.io/notecard/notecard-walkthrough/inbound-requests-and-shared-data.md#miscellaneous-file-requests)

## file.clear {#file-clear}

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

> **Note:**
>
> This request is not available in the currently selected Notecard firmware version.

## file.delete {#file-delete}

Supported on

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

Deletes Notefiles and the Notes they contain.

Arguments

### `files` {#file-delete--files}

*array of string*

One or more files to delete.

**Delete Multiple Files**

**JSON**

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

**C/C++**

```cpp
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**

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

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

**C/C++**

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

NoteRequest(req);
```

**Python**

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

Related Articles

- [Miscellaneous File Requests](https://dev.blues.io/notecard/notecard-walkthrough/inbound-requests-and-shared-data.md#miscellaneous-file-requests)

## file.stats {#file-stats}

Supported on

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

Gets resource statistics about local Notefiles.

Arguments

### `file` {#file-stats--file}

*string (optional)*

Returns the stats for the specified Notefile only.

**Get All File Stats**

**JSON**

```json
{
  "req": "file.stats"
}
```

**C/C++**

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

NoteRequest(req);
```

**Python**

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

Get resource statistics for all Notefiles.

**Get Specific File Stats**

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

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

Get resource statistics for a specific Notefile.

**Response Members**

### `changes` {#file-stats--changes}

*integer*

The number of Notes pending sync. Reflects only the Notefile named by the `file` argument, or all Notefiles when `file` is omitted.

### `sync` {#file-stats--sync}

*boolean*

`true` if a sync is recommended. This is set when an in-scope Notefile's in-memory footprint reaches a critical size and should be flushed, not when a particular number of Notes is pending.

### `total` {#file-stats--total}

*integer*

The total number of Notes, synced and unsynced. Reflects only the Notefile named by the `file` argument, or all Notefiles when `file` is omitted.

Example Response

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

Response with resource statistics showing pending sync recommendation.

```json
{
  "total": 25
}
```

Response when no changes are pending sync.

Related Articles

- [Miscellaneous File Requests](https://dev.blues.io/notecard/notecard-walkthrough/inbound-requests-and-shared-data.md#miscellaneous-file-requests)

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