# Emoncms API

> Emoncms is an open source web application for processing, logging and visualising energy, temperature and other environmental data. This is the complete HTTP API reference for https://emoncms.org/, generated from the same definitions as the interactive explorer at https://emoncms.org/site/api. A structured JSON version is available at https://emoncms.org/site/api.json.

Base URL: `https://emoncms.org/`

All endpoints are HTTP GET unless marked POST. Responses are JSON unless an endpoint's notes say otherwise. Failures usually respond `{"success": false, "message": "..."}`. Example URLs below are shown unencoded for readability: URL-encode parameter values (JSON in particular) in real requests, or let your HTTP library encode them for you.

## Authentication

Every account has two API keys, shown on https://emoncms.org/site/api when logged in:

- **Read only key**: for reading data and configuration, safe to use in dashboards and shared links.
- **Read & write key**: lets devices and scripts post data and change configuration.

Each endpoint below states which key it requires. Pass the key in one of three ways:

1. POST body parameter: `apikey=APIKEY` (recommended for POST requests)
2. HTTP header: `Authorization: Bearer APIKEY`
3. URL query parameter: `?apikey=APIKEY`

Endpoints marked *public ok* can also be used without a key for feeds a user has marked public, either with the owner's userid or via public profile routing: `https://emoncms.org/USERNAME/feed/list.json`.

For devices that cannot use HTTPS, emoncms also supports AES-128-CBC encrypted posting using the write key as a pre-shared key: see the encrypted post endpoint in the input section.

## Quick start (Python)

```python
import requests

base = "https://emoncms.org/"
apikey = "YOUR_WRITE_APIKEY"

# Post a reading to an input called power1 on a device called emontx
r = requests.get(base + "input/post", params={
    "node": "emontx",
    "fulljson": '{"power1":100}',
    "apikey": apikey
})
print(r.json())  # {"success": true}

# List feeds, then read the last week of daily data from the first one
feeds = requests.get(base + "feed/list.json", params={"apikey": apikey}).json()
data = requests.get(base + "feed/data.json", params={
    "id": feeds[0]["id"],
    "start": "-1 week", "end": "now", "interval": "daily",
    "apikey": apikey
}).json()  # [[unixtime_ms, value], ...]
```

## Input API

Inputs receive posted data. Each input holds the latest value and a process list describing what to do with new values, typically logging to a feed.

### Posting data

#### Post data (JSON)

`GET input/post`, requires the write API key

```
GET https://emoncms.org/input/post?node=emontx&fulljson={"power1":100,"power2":200,"power3":300}&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `node` | `emontx` | Node name, max 16 characters |
| `fulljson` | `{"power1":100,"power2":200,"power3":300}` | Strict JSON, recommended for new integrations |

Responds {"success": true} when the fulljson parameter is used, plain text 'ok' otherwise. The node name can also be given as a sub-action: input/post/emontx. Legacy parameters json={power1:100} and csv=100,200,300 are parsed leniently: non-numeric values are silently skipped.

#### Post data (CSV)

`GET input/post`, requires the write API key

```
GET https://emoncms.org/input/post?node=emontx&csv=100,200,300&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `node` | `emontx` | Node name, max 16 characters |
| `csv` | `100,200,300` | Values are named 1,2,3... in order |

#### Post data with timestamp

`GET input/post`, requires the write API key

```
GET https://emoncms.org/input/post?node=emontx&fulljson={"power1":100}&time=1787354464&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `node` | `emontx` |  |
| `fulljson` | `{"power1":100}` |  |
| `time` | `1787354464` | Unix timestamp in seconds (not milliseconds) |

Time may also be included as a 'time' key inside the JSON data, as a unix timestamp or ISO8601 string. The time parameter takes precedence if both are given.

#### Bulk upload

`GET input/bulk`, requires the write API key

```
GET https://emoncms.org/input/bulk?data=[[0,16,1137],[2,17,1437,3164],[4,19,1412,3077]]&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `data` | `[[0,16,1137],[2,17,1437,3164],[4,19,1412,3077]]` | Array of updates: [interval, node, value1, value2...] |

Without a time parameter the last row is taken as 'now' and earlier rows are offset relative to it. A value may also be an object to name the input, e.g [4,19,{"power":1412}]. Rows with fewer than 3 elements are skipped.

#### Bulk upload with offset

`GET input/bulk`, requires the write API key

```
GET https://emoncms.org/input/bulk?data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&offset=-10&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `data` | `[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]` |  |
| `offset` | `-10` | Row times are relative to now + offset |

#### Bulk upload with sentat time

`GET input/bulk`, requires the write API key

```
GET https://emoncms.org/input/bulk?data=[[520,16,1137],[530,17,1437,3164],[535,19,1412,3077]]&sentat=543&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `data` | `[[520,16,1137],[530,17,1437,3164],[535,19,1412,3077]]` |  |
| `sentat` | `543` | Positive increasing time index of the moment of sending |

#### Bulk upload with absolute time

`GET input/bulk`, requires the write API key

```
GET https://emoncms.org/input/bulk?data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&time=1787354464&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `data` | `[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]` |  |
| `time` | `1787354464` | Unix timestamp the row offsets are relative to |

#### Encrypted post

`GET input/post`, requires the write API key

For devices without HTTPS: POST to input/post or input/bulk with header Content-Type: aes128cbc (or aes128cbcgz) and Authorization: USERID:HMAC_SHA256. Body is base64(IV + ciphertext) of a standard request string, AES-128-CBC encrypted with the write apikey as pre-shared key. The response is a base64 sha256 hash of the decrypted payload for verification.

### Listing inputs

#### List nodes and inputs

`GET input/get`, requires the read API key

```
GET https://emoncms.org/input/get?apikey=APIKEY_READ
```

Returns {node: {input: {time, value, processList}}} for all nodes.

#### List inputs for a node

`GET input/get`, requires the read API key

```
GET https://emoncms.org/input/get?node=emontx&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `node` | `emontx` | Can also be given as sub-action: input/get/emontx |

#### Get a specific input

`GET input/get`, requires the read API key

```
GET https://emoncms.org/input/get?node=emontx&name=power1&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `node` | `emontx` |  |
| `name` | `power1` | Can also be given as sub-action: input/get/emontx/power1 |

#### List inputs with latest values

`GET input/list`, requires the read API key

```
GET https://emoncms.org/input/list?apikey=APIKEY_READ
```

Flat list with id, nodeid, name, description, processList, time and value.

#### List inputs configuration

`GET input/getinputs`, requires the read API key

```
GET https://emoncms.org/input/getinputs?apikey=APIKEY_READ
```

Returns {node: {input: {id, processList}}} without last time and value. input/get_inputs is an alias.

### Managing inputs

#### Set input fields

`GET input/set`, requires the write API key

```
GET https://emoncms.org/input/set?inputid=1&fields={"description":"Input Description"}&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `inputid` | `1` |  |
| `fields` | `{"description":"Input Description"}` | Only name and description can be set |

#### Set descriptions for multiple inputs

`POST input/set-descriptions`, requires the write API key

```
POST https://emoncms.org/input/set-descriptions
body: inputs=[{"id":1,"description":"Power"}]&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `inputs` | `[{"id":1,"description":"Power"}]` | Must be sent in the POST body |

#### Set descriptions for a node's inputs

`GET input/set-node-input-descriptions`, requires the write API key

```
GET https://emoncms.org/input/set-node-input-descriptions?node=emontx&names=Power 1,Power 2,Power 3&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `node` | `emontx` |  |
| `names` | `Power 1,Power 2,Power 3` | Comma-separated, applied in input id order |

#### Delete an input

`GET input/delete`, requires the write API key

```
GET https://emoncms.org/input/delete?inputid=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `inputid` | `1` |  |

#### Delete multiple inputs

`GET input/delete`, requires the write API key

```
GET https://emoncms.org/input/delete?inputids=[1,2]&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `inputids` | `[1,2]` | JSON array of input ids |

#### Delete inputs without a process list

`GET input/clean`, requires the write API key

```
GET https://emoncms.org/input/clean?apikey=APIKEY_WRITE
```

Responds in plain text with the number of inputs deleted.

#### Remove processes referencing deleted feeds

`GET input/cleanprocesslistfeeds`, requires the write API key

```
GET https://emoncms.org/input/cleanprocesslistfeeds?apikey=APIKEY_WRITE
```

Responds in plain text with a report of the process list entries removed.

#### Disable automatic input creation

`GET input/disable`, requires the write API key

```
GET https://emoncms.org/input/disable?apikey=APIKEY_WRITE
```

Posted data for inputs that do not already exist is discarded until input/enable is called. Check the current state with input/isdisabled.

#### Enable automatic input creation

`GET input/enable`, requires the write API key

```
GET https://emoncms.org/input/enable?apikey=APIKEY_WRITE
```

#### Check if input creation is disabled

`GET input/isdisabled`, requires the write API key

```
GET https://emoncms.org/input/isdisabled?apikey=APIKEY_WRITE
```

### Process lists

#### Get input process list

`GET input/process/get`, requires the write API key

```
GET https://emoncms.org/input/process/get?inputid=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `inputid` | `1` |  |

Returns the stored short form e.g. process__log_to_feed:1,process__scale:0.1

#### Set input process list

`POST input/process/set`, requires the write API key

```
POST https://emoncms.org/input/process/set?inputid=1
body: processlist=[{"fn":"process__log_to_feed","args":[1]}]&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `inputid` | `1` |  |
| `processlist` | `[{"fn":"process__log_to_feed","args":[1]}]` | Must be sent in the POST body |

JSON array of {fn, args} entries. Process function names and argument types are listed by process/list.json. The legacy colon/comma format is no longer accepted when setting.

#### Reset input process list

`GET input/process/reset`, requires the write API key

```
GET https://emoncms.org/input/process/reset?inputid=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `inputid` | `1` |  |

## Feed API

Feeds are stored time series. Fixed interval PHPFina feeds (engine 5) and variable interval PHPTimeSeries feeds (engine 2) are created by input process lists or directly via feed/create.json.

### Feed list & metadata

#### List feeds

`GET feed/list.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/list.json?meta=1&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `meta` | `1` | Include engine meta: start time, interval, size. 0 or 1 |

feed/listwithmeta.json is a legacy alias of feed/list.json?meta=1. A user's public feeds can be listed without an apikey via /username/feed/list.json.

#### List public feeds of a user

`GET feed/list.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/list.json?userid=1&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `userid` | `1` | Returns only feeds that user has marked public |

#### Get feed id from name

`GET feed/getid.json`, requires the read API key

```
GET https://emoncms.org/feed/getid.json?name=Power&tag=Test&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `name` | `Power` |  |
| `tag` | `Test` | Optional |

Responds in plain text with the feed id.

#### Get feed field

`GET feed/get.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/get.json?id=1&field=name&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `field` | `name` |  |

#### Get all feed fields

`GET feed/aget.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/aget.json?id=1&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |

#### Get feed meta

`GET feed/getmeta.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/getmeta.json?id=1&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |

Returns start_time, interval and npoints for fixed interval engines.

#### Get feed size on disk

`GET feed/getfeedsize.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/getfeedsize.json?id=1&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |

#### Get feed data checksum

`GET feed/sha256sum.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/sha256sum.json?id=1&npoints=0&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `npoints` | `0` | Number of most recent datapoints to include, 0 = whole feed |

PHPFina and PHPTimeSeries feeds only.

### Reading data

#### Last updated time and value for feed

`GET feed/timevalue.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/timevalue.json?id=1&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |

#### Last value of a given feed

`GET feed/value.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/value.json?id=1&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |

#### Fetch a value at a given time

`GET feed/value.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/value.json?id=1&time=0&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `time` | `0` | Unix timestamp in seconds |

#### Last value for multiple feeds

`GET feed/fetch.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/fetch.json?ids=1,2,3&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `ids` | `1,2,3` |  |

Values are returned in the order requested. false indicates a missing feed or no access, null is a valid empty value.

#### Fetch data from a feed

`GET feed/data.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/data.json?id=1&start=0&end=0&interval=60&average=0&delta=0&timeformat=unix&skipmissing=0&limitinterval=0&dp=-1&timezone=&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `start` | `0` | Unix time in seconds or milliseconds, or any php date string e.g: -1 week, or 01-12-2021 |
| `end` | `0` | Same formats as start, e.g: now |
| `interval` | `60` | Seconds, 0 = auto (~800 points), or timezone aligned: daily, weekly, monthly, annual |
| `average` | `0` | Mean of each interval rather than the value at its start. 0 or 1 |
| `delta` | `0` | Difference per interval, turns cumulative kWh feeds into kWh per interval. 0 or 1 |
| `timeformat` | `unix` | unix: seconds, unixms: milliseconds. One of: unix, unixms, excel, iso8601, notime |
| `skipmissing` | `0` | Omit null datapoints. 0 or 1 |
| `limitinterval` | `0` | Limit interval to the feed's native interval. 0 or 1 |
| `dp` | `-1` | Round values to N decimal places, -1 = off |
| `timezone` | `` | Used for date strings and aligned intervals, defaults to the account timezone |

Maximum 70000 datapoints per request. If timeformat is not given, response times are unix milliseconds (unixms). The legacy mode parameter is an alias of interval. feed/average.json is a shortcut for average=1.

#### Fetch data from multiple feeds

`GET feed/data.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/data.json?ids=1,2,3&start=0&end=0&interval=60&timeformat=unix&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `ids` | `1,2,3` |  |
| `start` | `0` |  |
| `end` | `0` |  |
| `interval` | `60` |  |
| `timeformat` | `unix` | unix: seconds, unixms: milliseconds. One of: unix, unixms, excel, iso8601, notime |

Returns [{feedid, data}, ...] rather than a bare data array. average and delta accept comma separated per-feed values, e.g. delta=1,0,1.

#### CSV export

`GET feed/csvexport.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/feed/csvexport.json?id=1&start=0&end=0&interval=60&timeformat=excel&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `start` | `0` |  |
| `end` | `0` |  |
| `interval` | `60` |  |
| `timeformat` | `excel` | One of: unix, unixms, excel, iso8601, notime |

Streams a CSV file download. Equivalent to feed/data.json with csv=1, which also supports multi-column export with ids=1,2,3.

### Writing data

#### Insert or update data point

`GET feed/post.json`, requires the write API key

```
GET https://emoncms.org/feed/post.json?id=1&time=0&value=100&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `time` | `0` | Unix timestamp in seconds |
| `value` | `100` |  |

feed/insert.json and feed/update.json are legacy aliases of feed/post.json.

#### Insert or update multiple data points

`GET feed/post.json`, requires the write API key

```
GET https://emoncms.org/feed/post.json?id=1&data=[[1787354460,100],[1787354470,150],[1787354480,200],[1787354490,250]]&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `data` | `[[1787354460,100],[1787354470,150],[1787354480,200],[1787354490,250]]` | [[time,value],...] in GET or POST |

#### Bulk binary upload

`GET feed/upload.json`, requires the write API key

POST raw binary body of float32 values with query parameters id, start, interval and npoints. Fixed interval PHPFina feeds only. Used by the sync and backup modules.

#### Sync feed data

`GET feed/sync.json`, requires the write API key

POST raw binary body of checksum framed feed segments, as sent by the emoncms sync module. PHPFina and PHPTimeSeries feeds only. Responds with updated feed meta.

### Managing feeds

#### Create new feed

`GET feed/create.json`, requires the write API key

```
GET https://emoncms.org/feed/create.json?tag=Test&name=Power&engine=5&options={"interval":10}&unit=W&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `tag` | `Test` |  |
| `name` | `Power` |  |
| `engine` | `5` | 5: PHPFina fixed interval, 2: PHPTimeSeries variable interval |
| `options` | `{"interval":10}` | PHPFina interval in seconds, minimum 10 |
| `unit` | `W` | Optional, max 10 characters |

Returns {"success":true, "feedid":N, "feed":{...}} on success. Use the feedid in a log to feed process or when posting data directly.

#### Delete existent feed

`GET feed/delete.json`, requires the write API key

```
GET https://emoncms.org/feed/delete.json?id=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |

#### Update feed fields

`GET feed/set.json`, requires the write API key

```
GET https://emoncms.org/feed/set.json?id=1&fields={"name":"anewname"}&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `fields` | `{"name":"anewname"}` | name, tag, unit and public can be set |

The tag:name combination must be unique. Set public to make a feed readable without an apikey.

#### Update multiple feeds

`POST feed/set-multiple.json`, requires the write API key

```
POST https://emoncms.org/feed/set-multiple.json
body: feeds=[{"id":1,"name":"Power"}]&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `feeds` | `[{"id":1,"name":"Power"}]` | Must be sent in the POST body |

#### Clear all feed data

`GET feed/clear.json`, requires the write API key

```
GET https://emoncms.org/feed/clear.json?id=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |

Deletes all datapoints but keeps the feed.

#### Trim feed data before time

`GET feed/trim.json`, requires the write API key

```
GET https://emoncms.org/feed/trim.json?id=1&start_time=0&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `start_time` | `0` | Unix timestamp, datapoints before this are removed |

#### Scale a range of values

`GET feed/scalerange.json`, requires the write API key

```
GET https://emoncms.org/feed/scalerange.json?id=1&start=0&end=0&value=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `start` | `0` |  |
| `end` | `0` |  |
| `value` | `1` | Scale factor |

PHPFina feeds only.

#### Refresh feed disk use

`GET feed/updatesize.json`, requires the write API key

```
GET https://emoncms.org/feed/updatesize.json?apikey=APIKEY_WRITE
```

### Virtual feed process list

#### Get feed process list

`GET feed/process/get.json`, requires the write API key

```
GET https://emoncms.org/feed/process/get.json?id=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |

Virtual feeds only. Returns the stored short form e.g. process__source_feed_data_time:1

#### Set feed process list

`POST feed/process/set.json`, requires the write API key

```
POST https://emoncms.org/feed/process/set.json?id=1
body: processlist=[{"fn":"process__source_feed_data_time","args":[1]}]&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |
| `processlist` | `[{"fn":"process__source_feed_data_time","args":[1]}]` | Must be sent in the POST body |

JSON array of {fn, args} entries, virtual feeds only. Process function names and argument types are listed by process/list.json?context=1. The legacy colon/comma format is no longer accepted when setting.

#### Reset feed process list

`GET feed/process/reset.json`, requires the write API key

```
GET https://emoncms.org/feed/process/reset.json?id=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Feed id, see feed/list.json. |

## Device API

Devices group the inputs posted to one node name and can initialise inputs, feeds and process lists from a template.

### Device list & details

#### List devices

`GET device/list.json`, requires the read API key

```
GET https://emoncms.org/device/list.json?apikey=APIKEY_READ
```

Returns id, nodeid, name, description, type, devicekey and the time of the last update for every device in the account, ordered by nodeid then name.

#### Get device details

`GET device/get.json`, requires the write API key

```
GET https://emoncms.org/device/get.json?id=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` | Device id, as returned by device/list.json |

Responds {"success": false, "message": "Device does not exist"} for an unknown id. The devicekey is included in the response, so a read only key is not accepted here.

### Managing devices

#### Create a device

`GET device/create.json`, requires the write API key

```
GET https://emoncms.org/device/create.json?nodeid=emontx&name=Test&description=House&type=&dkey=&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `nodeid` | `emontx` | Must be unique within the account, this is the node name inputs are posted to |
| `name` | `Test` | Optional, defaults to the nodeid |
| `description` | `House` | Optional |
| `type` | `` | Optional device template type, e.g. emontx3, see device/template/listshort.json |
| `dkey` | `` | Optional device key, 32 hexadecimal characters |

Returns the new device id. Creating a device does not create its inputs and feeds, call device/init.json afterwards to apply the template. Names, nodeids and descriptions accept letters, numbers, spaces and _ - : . only.

#### Create and initialise a device

`GET device/autocreate.json`, requires the write API key

```
GET https://emoncms.org/device/autocreate.json?nodeid=emontx&type=emontx3&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `nodeid` | `emontx` | Node name the device posts inputs to |
| `type` | `emontx3` | Device template type |

Used by the input name describe mechanism to register a device in one call. Creates the device if the nodeid is not already in use, names it nodeid:type and then initialises it from the template. Calling it again for an existing nodeid re-runs the template.

#### Update device fields

`GET device/set.json`, requires the write API key

```
GET https://emoncms.org/device/set.json?id=1&fields={"name":"anewname"}&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` |  |
| `fields` | `{"name":"anewname"}` | name, description, nodeid, type and devicekey can be set |

Only the fields present in the JSON object are changed. A devicekey must be exactly 32 hexadecimal characters: use device/generatekey.json to create one.

#### Delete a device

`GET device/delete.json`, requires the write API key

```
GET https://emoncms.org/device/delete.json?id=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` |  |

Removes the device registration only. The inputs and feeds it created are left in place.

#### Remove inactive devices and inputs

`GET device/clean`, requires the write API key

```
GET https://emoncms.org/device/clean?active=3600&dryrun=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `active` | `3600` | Seconds, inputs not updated within this time are treated as inactive |
| `dryrun` | `1` | List what would be removed without changing anything. 0 or 1 |

Responds in plain text with a summary of what was, or would be, removed. Inactive inputs that are not logging to a feed are deleted, along with any device left without inputs. Always run with dryrun=1 first.

### Device keys

#### Generate a random device key

`GET device/generatekey.json`, requires the write API key

```
GET https://emoncms.org/device/generatekey.json?apikey=APIKEY_WRITE
```

Returns a new random key without saving it. Apply it with device/set.json and fields={"devicekey":"..."}, or use device/setnewdevicekey.json to generate and save in one call.

#### Set a new random device key

`GET device/setnewdevicekey.json`, requires the write API key

```
GET https://emoncms.org/device/setnewdevicekey.json?id=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` |  |

Generates a new key and saves it against the device, replacing any existing key. Anything posting with the old key stops working.

### Device templates

#### List template metadata

`GET device/template/listshort.json`, requires the write API key

```
GET https://emoncms.org/device/template/listshort.json?apikey=APIKEY_WRITE
```

Name, category, group and description for every available template, keyed by the type string used in device/create.json. Use this to pick a device type.

#### List templates in full

`GET device/template/list.json`, requires the write API key

```
GET https://emoncms.org/device/template/list.json?apikey=APIKEY_WRITE
```

The complete definitions, including the inputs, feeds and process lists of every template. This is a large response, device/template/listshort.json is usually enough.

#### Get template details

`GET device/template/get.json`, requires the write API key

```
GET https://emoncms.org/device/template/get.json?type=emontx3&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `type` | `emontx3` | Template type string, see device/template/listshort.json |

#### Prepare device initialization

`GET device/template/prepare.json`, requires the write API key

```
GET https://emoncms.org/device/template/prepare.json?id=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` |  |

Returns the inputs, feeds and process lists the device type's template would create, each marked with whether it already exists. Nothing is created. Edit this result and send it back to device/template/init.json to control what is applied. Adding type=... to the request sets the device type before preparing, so pass it only when you mean to change the type.

#### Prepare a custom template

`POST device/template/prepare_custom.json`, requires the write API key

```
POST https://emoncms.org/device/template/prepare_custom.json?id=1
body: template={"feeds":[],"inputs":[]}&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` |  |
| `template` | `{"feeds":[],"inputs":[]}` | Template JSON, must be sent in the POST body |

As prepare, but for a template supplied in the request rather than the device type's stored template.

#### Initialize device from its template

`GET device/init.json`, requires the write API key

```
GET https://emoncms.org/device/init.json?id=1&template=&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` |  |
| `template` | `` | Optional prepared template JSON, leave empty to apply the device type's default |

Creates the inputs, feeds and process lists defined by the device type. A device should only need initializing once: initializing twice duplicates its inputs and feeds. The template parameter may be sent in the query string or the POST body.

#### Initialize device with a prepared template

`POST device/template/init.json`, requires the write API key

```
POST https://emoncms.org/device/template/init.json?id=1
body: template={"feeds":[],"inputs":[]}&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` |  |
| `template` | `{"feeds":[],"inputs":[]}` | Prepared template JSON, must be sent in the POST body |

Takes the result of device/template/prepare.json, so the caller decides which inputs and feeds are created. The device must have a type set.

#### Initialize device with a custom template

`POST device/template/init_custom.json`, requires the write API key

```
POST https://emoncms.org/device/template/init_custom.json?id=1
body: template={"feeds":[],"inputs":[]}&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` |  |
| `template` | `{"feeds":[],"inputs":[]}` | Template JSON, must be sent in the POST body |

Applies a template supplied in the request, no device type is required.

#### Generate a template from a device

`GET device/template/generate.json`, requires the write API key

```
GET https://emoncms.org/device/template/generate.json?id=1&apikey=APIKEY_WRITE
```

| Parameter | Example | Description |
|---|---|---|
| `id` | `1` |  |

Builds a template definition from the device's existing inputs, feeds and process lists, the reverse of initialization. Useful for turning a configured device into a reusable template file.

## Process API

Process lists are configured through the input and feed modules, these endpoints list the available process functions.

### Available processes

#### List all processes

`GET process/list.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/process/list.json?apikey=APIKEY_READ
```

Every process the server supports, keyed by its function name, e.g. process__log_to_feed. Each entry gives id_num, name, short, group, description and an args array describing the argument types the process takes. This is the list to work from when building a process list.

#### List processes valid for a context

`GET process/list.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/process/list.json?context=0&apikey=APIKEY_READ
```

| Parameter | Example | Description |
|---|---|---|
| `context` | `0` | 0: input process list, 1: virtual feed process list. One of: 0, 1 |

The same list filtered to the processes that are valid in that context, with deleted processes removed. Not every process makes sense on a virtual feed: log to feed, for example, is input only.

#### Process id to name map

`GET process/map.json`, requires the read API key, public ok: no key needed for public feeds

```
GET https://emoncms.org/process/map.json?apikey=APIKEY_READ
```

Maps the numeric id_num stored in legacy process lists to the process function name, e.g. 1: process__log_to_feed. Use it to read process lists saved in the old colon and comma format.

## More resources

- Interactive API explorer: https://emoncms.org/site/api
- Emoncms guide: https://docs.openenergymonitor.org/emoncms/index.html
- OpenEnergyMonitor documentation: https://docs.openenergymonitor.org
- Community forum: https://community.openenergymonitor.org
- Emoncms source code: https://github.com/emoncms/emoncms