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:
- Use POST parameter (Recommended): "apikey=APIKEY"
- Add the HTTP header: "Authorization: Bearer APIKEY"
- Append on the URL of your request: &apikey=APIKEY
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:
- input/post - Post a single update from a node.
- input/bulk - Bulk upload historic data from multiple nodes in a single update.
- Encrypted - An encrypted version of both of the above
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).
Description | Method | Example |
---|---|---|
JSON format | GET | https://emoncms.org/input/post?node=emontx&fulljson={"power1":100,"power2":200,"power3":300} |
JSON like format | GET | https://emoncms.org/input/post?node=emontx&json={power1:100,power2:200,power3:300} |
CSV format | GET | https://emoncms.org/input/post?node=mynode&csv=100,200,300 |
Set the input entry time manually | GET | https://emoncms.org/input/post?time=1733511714&node=1&csv=100,200,300 |
Node name as sub-action | GET | https://emoncms.org/input/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: | GET | https://emoncms.org/input/post?node=emontx&fulljson={"power1":100,"power2":200,"power3":300}&apikey=APIKEY_WRITE |
JSON format: | POST | curl --data "node=1&data={power1:100,power2:200,power3:300}&apikey=APIKEY_WRITE" "https://emoncms.org/input/post" |
CSV format: | POST | curl --data "node=1&data=100,200,300&apikey=APIKEY_WRITE" "https://emoncms.org/input/post" |
input/bulk
Efficiently upload multiple updates from multiple nodes.
Description | Method | Example |
---|---|---|
Example request: | GET | https://emoncms.org/input/bulk?data=[[0,16,1137],[2,17,1437,3164],[4,19,1412,3077]] |
- The first number of each node is the time offset (see below).
- The second number is the node id, this is the unique identifier for the wireless node.
- All the numbers after the first two are data values. The second node here (node 17) has two data values: 1437 and 3164.
- Optional offset and time parameters allow the sender to set the time reference for the packets. If none is specified, it is assumed that the last packet just arrived. The time for the other packets is then calculated accordingly.
Legacy default format (4 is now, 2 is -2 seconds and 0 is -4 seconds to now): | GET | https://emoncms.org/input/bulk?data=[[0,16,1137],[2,17,1437,3164],[4,19,1412,3077]] |
Time offset format (-6 is -16 seconds to now): | GET | https://emoncms.org/input/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) | GET | https://emoncms.org/input/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)) | GET | https://emoncms.org/input/bulk?data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&time=1733511714 |
Named feeds (similar to the main example but updates the keys "data" and "anotherData" for node 19) | GET | https://emoncms.org/input/bulk?data=[[0,16,1137],[2,17,1437,3164],[4,19,{"data":1412},{"anotherData":3077}]] |
Legacy format: | POST | curl --data "data=[[0,16,1137],[2,17,1437,3164],[4,19,1412,3077]]&apikey=APIKEY_WRITE" "https://emoncms.org/input/bulk" |
Time offset format: | POST | curl --data "data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&offset=-10&apikey=APIKEY_WRITE" "https://emoncms.org/input/bulk" |
Sentat format: | POST | curl --data "data=[[520,16,1137],[530,17,1437,3164],[535,19,1412,3077]]&sentat=543&apikey=APIKEY_WRITE" "https://emoncms.org/input/bulk" |
Absolute time format: | POST | curl --data "data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&time=1733511714&apikey=APIKEY_WRITE" "https://emoncms.org/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.
Description | Method | Example |
---|---|---|
GET/POST | URL: /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: | GET | https://emoncms.org/input/get |
List inputs for specific node: | GET | https://emoncms.org/input/get/emontx |
Fetch specific input from node: | GET | https://emoncms.org/input/get/emontx/power1 |
Input actions
List of inputs with latest data | GET | https://emoncms.org/input/list |
Get inputs configuration (last time and value not included) | GET | https://emoncms.org/input/get_inputs |
Set input fields | GET | https://emoncms.org/input/set?inputid=0&fields={'description':'Input Description'} |
Delete an input | GET | https://emoncms.org/input/delete?inputid=0 |
Clean inputs without a process list | GET | https://emoncms.org/input/clean |