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

      DescriptionMethodExample
      JSON formatGEThttp://emoncms.org/input/post?node=emontx&fulljson={"power1":100,"power2":200,"power3":300}
      JSON like formatGEThttp://emoncms.org/input/post?node=emontx&json={power1:100,power2:200,power3:300}
      CSV formatGEThttp://emoncms.org/input/post?node=mynode&csv=100,200,300
      Set the input entry time manuallyGEThttp://emoncms.org/input/post?time=1713558141&node=1&csv=100,200,300
      Node name as sub-actionGEThttp://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:GEThttp://emoncms.org/input/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" "http://emoncms.org/input/post"
      CSV format:POSTcurl --data "node=1&data=100,200,300&apikey=APIKEY_WRITE" "http://emoncms.org/input/post"

      input/bulk

      Efficiently upload multiple updates from multiple nodes.

      DescriptionMethodExample
      Example request:GEThttp://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):GEThttp://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):GEThttp://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)GEThttp://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))GEThttp://emoncms.org/input/bulk?data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&time=1713558141
      Named feeds (similar to the main example but updates the keys "data" and "anotherData" for node 19)GEThttp://emoncms.org/input/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" "http://emoncms.org/input/bulk"
      Time offset format:POSTcurl --data "data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&offset=-10&apikey=APIKEY_WRITE" "http://emoncms.org/input/bulk"
      Sentat format:POSTcurl --data "data=[[520,16,1137],[530,17,1437,3164],[535,19,1412,3077]]&sentat=543&apikey=APIKEY_WRITE" "http://emoncms.org/input/bulk"
      Absolute time format:POSTcurl --data "data=[[-10,16,1137],[-8,17,1437,3164],[-6,19,1412,3077]]&time=1713558141&apikey=APIKEY_WRITE" "http://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.

      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:GEThttp://emoncms.org/input/get
      List inputs for specific node:GEThttp://emoncms.org/input/get/emontx
      Fetch specific input from node:GEThttp://emoncms.org/input/get/emontx/power1

      Input actions

      List of inputs with latest dataGEThttp://emoncms.org/input/list
      Get inputs configuration (last time and value not included)GEThttp://emoncms.org/input/get_inputs
      Set input fieldsGEThttp://emoncms.org/input/set?inputid=0&fields={'description':'Input Description'}
      Delete an inputGEThttp://emoncms.org/input/delete?inputid=0
      Clean inputs without a process listGEThttp://emoncms.org/input/clean