---
title: env Requests - API Reference
description: Environment variables are key-value pairs that can be set on a Notecard device, project, or fleet.
source_url: https://dev.blues.io/api-reference/notecard-api/env-requests/
canonical_url: https://dev.blues.io/api-reference/notecard-api/env-requests/
markdown_url: https://dev.blues.io/api-reference/notecard-api/env-requests.md
---

# env Requests

Environment variables are key-value pairs that can be set on a device, project, or fleet.

## env.default

Supported on

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

Used by the Notecard host to specify a default value for an environment variable until that variable is overridden by a device, project or fleet-wide setting at Notehub.

> **Note:**
>
> Environment variables set with `env.default` on **Notecard LoRa** do not propagate up to Notehub. If looking for a simple way to share a variable from a Notecard to Notehub, please refer to [var.set](https://dev.blues.io/api-reference/notecard-api/var-requests/latest.md#var-set).

Arguments

### `name`

*string (optional)*

The name of the environment variable (case-insensitive).

### `sync`

*boolean (optional)*

Set to `true` to trigger an immediate sync.

### `text`

*string (optional)*

The value of the variable. Pass `""` or omit from the request to delete it.

**Set Default Environment Variable**

**JSON**

```json
{
  "req": "env.default",
  "name": "monitor-pump",
  "text": "on"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "monitor-pump");
JAddStringToObject(req, "text", "on");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.default"}
req["name"] = "monitor-pump"
req["text"] = "on"
rsp = card.Transaction(req)
```

Set a default value for an environment variable.

**Clear Default Environment Variable**

**JSON**

```json
{
  "req": "env.default",
  "name": "monitor-pump"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "monitor-pump");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.default"}
req["name"] = "monitor-pump"
rsp = card.Transaction(req)
```

Clear the default value for an environment variable by omitting text.

**Set Empty String Default**

**JSON**

```json
{
  "req": "env.default",
  "name": "debug-mode",
  "text": ""
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "debug-mode");
JAddStringToObject(req, "text", "");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.default"}
req["name"] = "debug-mode"
req["text"] = ""
rsp = card.Transaction(req)
```

Set an environment variable default to an empty string.

**Set Numeric Default**

**JSON**

```json
{
  "req": "env.default",
  "name": "sample-rate",
  "text": "60"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "sample-rate");
JAddStringToObject(req, "text", "60");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.default"}
req["name"] = "sample-rate"
req["text"] = "60"
rsp = card.Transaction(req)
```

Set a default value for a numeric environment variable.

**Set Default and Sync**

**JSON**

```json
{
  "req": "env.default",
  "name": "monitor-pump",
  "text": "on",
  "sync": true
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.default");
JAddStringToObject(req, "name", "monitor-pump");
JAddStringToObject(req, "text", "on");
JAddBoolToObject(req, "sync", true);

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.default"}
req["name"] = "monitor-pump"
req["text"] = "on"
req["sync"] = True
rsp = card.Transaction(req)
```

Set a default environment variable and trigger an immediate sync.

**Response Members**

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

## env.get

Supported on

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

Returns a single environment variable, or all variables according to precedence rules.

> **Note:**
>
> Before using the `env.get` API on Notecard for LoRa or Starnote, you must create an environment variable template using the [env.template API](https://dev.blues.io/api-reference/notecard-api/env-requests/latest.md#env-template).

Arguments

### `name`

*string (optional)*

The name of the environment variable (case-insensitive). Omit to return all environment variables known to the Notecard.

### `names`

*array of string (optional)*

A list of one or more variables to retrieve, by name (case-insensitive).

### `time`

*UNIX Epoch time (optional)*

Request a modified environment variable or variables from the Notecard, but only if modified after the time provided.

**Get Single Variable**

**JSON**

```json
{
  "req": "env.get",
  "name": "monitor-pump-one"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.get");
JAddStringToObject(req, "name", "monitor-pump-one");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.get"}
req["name"] = "monitor-pump-one"
rsp = card.Transaction(req)
```

Retrieve a specific environment variable by name.

**Get Single Variable With Modified Time**

**JSON**

```json
{
  "req": "env.get",
  "name": "monitor-pump-one",
  "time": 1656315835
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.get");
JAddStringToObject(req, "name", "monitor-pump-one");
JAddNumberToObject(req, "time", 1656315835);

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.get"}
req["name"] = "monitor-pump-one"
req["time"] = 1656315835
rsp = card.Transaction(req)
```

Retrieve a variable only if modified after the specified time.

**Get Multiple Variables**

**JSON**

```json
{
  "req": "env.get",
  "names": [
    "monitor-pump-one",
    "monitor-pump-two"
  ]
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.get");
J *names = JAddArrayToObject(req, "names");
JAddItemToArray(names, JCreateString("monitor-pump-one"));
JAddItemToArray(names, JCreateString("monitor-pump-two"));

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.get"}
req["names"] = ["monitor-pump-one", "monitor-pump-two"]
rsp = card.Transaction(req)
```

Retrieve multiple environment variables by name.

**Get All Variables**

**JSON**

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

**C/C++**

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

NoteRequest(req);
```

**Python**

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

Retrieve all environment variables known to the Notecard.

**Response Members**

### `body`

*object*

If a `name` was not specified, an object with `name` and `value` pairs for all environment variables.

### `text`

*string*

If a `name` was specified, the value of the environment variable.

### `time`

*UNIX Epoch time*

The time of the Notecard variable or variables change.

Example Response

```json
{
  "monitor-pump-one": "on",
  "time": 1656315835
}
```

Response for a single environment variable request.

```json
{
  "body": {
    "monitor-pump-one": "on",
    "monitor-pump-two": "off"
  },
  "time": 1656315835
}
```

Response for multiple environment variables request.

```json
{
  "body": {
    "monitor-pump-one": "on",
    "monitor-pump-two": "off",
    "monitor-pump-three": "on"
  },
  "time": 1656315835
}
```

Response for all environment variables request.

## env.modified

Supported on

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

Get the time of the update to any environment variable managed by the Notecard.

Arguments

### `time`

*UNIX Epoch time (optional)*

Request whether the Notecard has detected an environment variable change since a known epoch time.

**Get Environment Modified Time**

**JSON**

```json
{
  "req": "env.modified"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.modified");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.modified"}
rsp = card.Transaction(req)
```

Get the timestamp of the last environment variable change.

**Check Changes Since Time**

**JSON**

```json
{
  "req": "env.modified",
  "time": 1605814400
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.modified");
JAddNumberToObject(req, "time", 1605814400);

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.modified"}
req["time"] = 1605814400
rsp = card.Transaction(req)
```

Check if environment variables have been modified since a specific time.

**Response Members**

### `time`

*UNIX Epoch time*

Timestamp indicating the last time any environment variable was changed on the device.

Example Response

```json
{
  "time": 1605814493
}
```

## env.set

Supported on

(Cell, Cell+WiFi, Skylo, WiFi)

Sets a local environment variable on the Notecard. Local environment variables cannot be overridden by a Notehub variable of any scope.

> **Deprecated:**
>
> The `env.set` API is deprecated as of v7.2.2. We recommend setting environment variables in Notehub using either the Notehub user interface or [Notehub API](https://dev.blues.io/api-reference/notehub-api.md). You may also use the `env.default` API to provide a default value for an environment variable, until that variable is overridden by a value from Notehub.

Arguments

### `name`

*string (optional)*

The name of the environment variable (case-insensitive).

### `text`

*string (optional)*

The value of the variable. Pass `""` or omit from the request to delete it.

**Set Environment Variable**

**JSON**

```json
{
  "req": "env.set",
  "name": "monitor-pump",
  "text": "on"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.set");
JAddStringToObject(req, "name", "monitor-pump");
JAddStringToObject(req, "text", "on");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.set"}
req["name"] = "monitor-pump"
req["text"] = "on"
rsp = card.Transaction(req)
```

Set a local environment variable on the Notecard.

**Clear Environment Variable**

**JSON**

```json
{
  "req": "env.set",
  "name": "monitor-pump"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.set");
JAddStringToObject(req, "name", "monitor-pump");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.set"}
req["name"] = "monitor-pump"
rsp = card.Transaction(req)
```

Clear a local environment variable by omitting text.

**Set Empty String**

**JSON**

```json
{
  "req": "env.set",
  "name": "debug-mode",
  "text": ""
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.set");
JAddStringToObject(req, "name", "debug-mode");
JAddStringToObject(req, "text", "");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.set"}
req["name"] = "debug-mode"
req["text"] = ""
rsp = card.Transaction(req)
```

Set an environment variable to an empty string.

**Response Members**

### `time`

*UNIX Epoch time*

The logged time of the variable change.

Example Response

```json
{
  "time": 1605814493
}
```

## env.template

Supported on

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

The `env.template` request allows developers to provide a schema for the environment variables the Notecard uses. The provided template allows the Notecard to store environment variables as fixed-length binary records rather than as flexible JSON objects that require much more memory.

Using templated environment variables also allows the Notecard to optimize the network traffic related to sending and receiving environment variable updates.

> **Note:**
>
> The `env.template` request is required for using environment variables on Notecard LoRa and a Notecard paired with Starnote.

Arguments

### `body`

*object (optional)*

A sample JSON body that specifies environment variables 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 a full explanation of type hints.

**Define Environment Variable Template**

**JSON**

```json
{
  "req": "env.template",
  "body": {
    "env_var_int": 11,
    "env_var_string": "10"
  }
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.template");
J *body = JAddObjectToObject(req, "body");
JAddNumberToObject(body, "env_var_int", 11);
JAddStringToObject(body, "env_var_string", "10");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.template"}
req["body"] = {"env_var_int": 11, "env_var_string": "10"}
rsp = card.Transaction(req)
```

Provide a schema with data type hints for environment variables.

**Complex Template Example**

**JSON**

```json
{
  "req": "env.template",
  "body": {
    "enabled": true,
    "temperature": 23.5,
    "count": 42,
    "name": "sensor"
  }
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.template");
J *body = JAddObjectToObject(req, "body");
JAddBoolToObject(body, "enabled", true);
JAddNumberToObject(body, "temperature", 23.5);
JAddNumberToObject(body, "count", 42);
JAddStringToObject(body, "name", "sensor");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.template"}
req["body"] = {"enabled": true, "temperature": 23.5, "count": 42, "name": "sensor"}
rsp = card.Transaction(req)
```

Template with multiple data types including boolean and float.

**Clear Template**

**JSON**

```json
{
  "req": "env.template"
}
```

**C/C++**

```cpp
J *req = NoteNewRequest("env.template");

NoteRequest(req);
```

**Python**

```python
req = {"req": "env.template"}
rsp = card.Transaction(req)
```

Clear the environment variable template by omitting the body.

**Response Members**

### `bytes`

*integer*

The maximum number of bytes that will be used when environment variables are communicated or stored, so long as the variables do not include variable-length strings.

Example Response

```json
{
  "bytes": 22
}
```

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