---
title: file Requests - API Reference
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/
canonical_url: https://dev.blues.io/api-reference/notecard-api/file-requests/
markdown_url: https://dev.blues.io/api-reference/notecard-api/file-requests.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

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`

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

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

**Use Change Tracker**

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

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

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

**C/C++**

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

NoteRequest(req);
```

**Python**

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

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

## file.changes.pending

Supported on

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

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

Arguments

None

**Example**

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

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

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

## file.clear

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Used to clear the contents of a specified outbound (`.qo`/`.qos`) Notefile, deleting all pending Notes.

Arguments

### `file`

*string*

The name of the Notefile whose Notes you wish to delete.

**Clear Outbound Notefile**

**JSON**

```json
{
  "req": "file.clear",
  "file": "data.qo"
}
```

**C/C++**

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

NoteRequest(req);
```

**Python**

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

Clear all pending Notes from an outbound Notefile.

**Clear Encrypted Outbound Notefile**

**JSON**

```json
{
  "req": "file.clear",
  "file": "sensors.qos"
}
```

**C/C++**

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

NoteRequest(req);
```

**Python**

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

Clear all pending Notes from an encrypted outbound Notefile.

**Response Members**

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

## file.delete

Supported on

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

Deletes Notefiles and the Notes they contain.

Arguments

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

## file.stats

Supported on

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

Gets resource statistics about local Notefiles.

Arguments

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

*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

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

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