API Documentation

Authentication

If you want to call any of the following actions when your not logged in you can authenticate with an API key:

  • Append on the URL of your request: &apikey=APIKEY
  • Use POST parameter: "apikey=APIKEY"
  • Add the HTTP header: "Authorization: Bearer APIKEY"

API keys

There are two types of api key the write apikey and read apikey giving read & write access or read-only access. Login or create an account to obtain these keys.

Input API

Apikey authentication

If you want to call any of the following actions when your not logged in you can authenticate with your API key:

Alternatively use the encrypted input method to post data with higher security where HTTPS is not available.

Posting data to EmonCMS

The EmonCMS input API provides three ways of sending data to emoncms:

If your starting out with EmonCMS 'input/post' is a good starting point for testing, this was the original input method when EmonCMS . The EmonPi/EmonBase uses the 'input/bulk' input method to post to a remote emoncms server as this method provides the option to efficiently bulk upload buffered data after an internet connection outage. Combining multiple updates in a single input/bulk request also reduces bandwidth requirements.

For applications where HTTPS or TLS is not available, emoncms offers an in-built transport layer encryption solution where the emoncms apikey is used as the pre-shared key for encrypting the data with AES-128-CBC.

input/post

The "fulljson" format is recommended for new integrations, it uses the PHP JSON decoder and answer is also in json.
The "json like" format is based on the CSV input parsing implementation and maintained for backwards compatibility.
A node name can be a name e.g: emontx or a number e.g: 10.
The input/post API is compatible with both GET and POST request methods (POST examples given use curl).

DescriptionMethodExample
JSON formatGETinput/post?node=emontx&fulljson={"power1":100,"power2":200,"power3":300}
JSON like formatGETinput/post?node=emontx&json={power1:100,power2:200,power3:300}
CSV formatGETinput/post?node=mynode&csv=100,200,300
Set the input entry time manuallyGETinput/post?time=1741948213&node=1&csv=100,200,300
Node name as sub-actionGETinput/post/emontx?fulljson={"power1":100,"power2":200,"power3":300}
To post data from a remote device you will need to include in the request url your write apikey. This give your device write access to your emoncms account, allowing it to post data. For example using the first json type request above just add the apikey to the end like this:GETinput/post?node=emontx&fulljson={"power1":100,"power2":200,"power3":300}&apikey=APIKEY_WRITE
JSON format:POSTcurl --data "node=1&data={power1:100,power2:200,power3:300}&apikey=APIKEY_WRITE" "input/post"
CSV format:POSTcurl --data "node=1&data=100,200,300&apikey=APIKEY_WRITE" "input/post"

input/bulk

Efficiently upload multiple updates from multiple nodes.

DescriptionMethodExample
Example request:GETinput/bulk?data=[[0,16,1137],[2,17,1437,3164],[4,19,1412,3077]]
Legacy default format (4 is now, 2 is -2 seconds and 0 is -4 seconds to now):GETinput/bulk?data=[[0,16,1137],[2,17,1437,3164],[4,19,1412,3077]]
Time offset format (-6 is -16 seconds to now):GETinput/bulk?data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&offset=-10
Sentat format: (useful for sending as positive increasing time index)GETinput/bulk?data=[[520,16,1137],[530,17,1437,3164],[535,19,1412,3077]]&sentat=543
Absolute time format (-6 is 1387730121 seconds since 1970-01-01 00:00:00 UTC))GETinput/bulk?data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&time=1741948213
Named feeds (similar to the main example but updates the keys "data" and "anotherData" for node 19)GETinput/bulk?data=[[0,16,1137],[2,17,1437,3164],[4,19,{"data":1412},{"anotherData":3077}]]
Legacy format:POSTcurl --data "data=[[0,16,1137],[2,17,1437,3164],[4,19,1412,3077]]&apikey=APIKEY_WRITE" "input/bulk"
Time offset format:POSTcurl --data "data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&offset=-10&apikey=APIKEY_WRITE" "input/bulk"
Sentat format:POSTcurl --data "data=[[520,16,1137],[530,17,1437,3164],[535,19,1412,3077]]&sentat=543&apikey=APIKEY_WRITE" "input/bulk"
Absolute time format:POSTcurl --data "data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&time=1741948213&apikey=APIKEY_WRITE" "input/bulk"

Encryption

For applications where HTTPS or TLS is not available, emoncms offers an in-built transport layer encryption solution where the emoncms apikey is used as the pre-shared key for encrypting the data with AES-128-CBC.
There is a PHP example of how to generate an encrypted request here: PHP Example source code.

1. Start with a request string conforming with the API options above e.g: node=emontx&data={power1:100,power2:200,power3:300}
2. Create an initialization vector.
3. Encrypt using AES-128-CBC.
4. Create a single string starting with the initialization vector followed by the cipher-text result of the AES-128-CBC encryption.
5. Convert to a base64 encoded string.
6. Generate a HMAC_HASH of the data string together, using the emoncms apikey for authorization.
7. Send the encrypted string in the POST body of a request to either input/post or input/bulk with headers properties 'Content-type' and 'Authorization' set as below
8. Verify the result. The result is a base64 encoded sha256 hash of the json data string.

DescriptionMethodExample
GET/POSTURL: /input/post or /input/bulk
HEADER: Authorization: USERID:HMAC_HASH, Content-Type: aes128cbc
POST BODY: IV+CIPHERTEXT

Fetching inputs, updating meta data and other actions


Input get

List all nodes and associated inputs:GETinput/get
List inputs for specific node:GETinput/get/emontx
Fetch specific input from node:GETinput/get/emontx/power1

Input actions

List of inputs with latest dataGETinput/list
Get inputs configuration (last time and value not included)GETinput/get_inputs
Set input fieldsGETinput/set?inputid=0&fields={'description':'Input Description'}
Delete an inputGETinput/delete?inputid=0
Clean inputs without a process listGETinput/clean