SFA RESTful API

SCADA Final Aggregator API is used to manage EVA ICS cloud and aggregated resources.

This document describes API methods for RESTful calls. For direct and JSON RPC calls look SFA API.

RESTful API basics

Majority EVA ICS API components and items support REST. Parameters for POST, PUT, PATCH and DELETE requests can be sent in both JSON and multipart/form-data. For JSON, Content-Type: application/json header must be specified.

Long API calls

Warning

It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.

Requests

API key can be sent in HTTP X-Auth-Key header (preferred) or in request parameters (as k).

  • GET request is used to get information about resource or list of resources of the specified type.
  • POST request is used to perform special API calls and create resources in case when resource id is generated by server. In the last case, response always contains additional field Location which points to the resource created.
  • PUT request is used to create new resources. If resource already exists, the server could refuse recreating it, responding with 409 Conflict HTTP error.
  • PATCH request is used to modify resource parameters.
  • DELETE request is used to delete resource.

For resource creation and modification, multiple parameters can be specified in a single request. For majority requests of such purpose, a special parameter “save” is used to tell server (if “save”: true) to save the resource configuration immediately after its modification.

For the group-related calls, put trailing slash at the end of the request URL:

/r/<resource_type>/<group>/

Responses

Success responses:

  • 200 OK API call completed successfully
  • 201 Created API call completed successfully, Response header Location contains either uri to the newly created object or resource is accessible by the effective request uri. For resources created with PUT, body contains either serialized resource object or resource type and id
  • 202 Accepted The server accepted command and will process it later.
  • 204 No Content API call completed successfully, no content to return

Error responses:

  • 403 Forbidden the API key has no access to this function or resource
  • 404 Not Found resource doesn’t exist
  • 405 Method Not Allowed API function/method not found
  • 409 Conflict resource/object already exists or is locked
  • 500 API Error API function execution has been failed. Check input parameters and server logs.

Response body may contain additional information encoded in JSON. { “result”: “OK” } and { “result”: “ERROR” } in body are not returned.

Contents

General functions

test API/key and get system info

Test can be executed with any valid API key of the controller the function is called to.

http

GET /r/core HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/core -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/core --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/core X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/core', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "acl": {
        "key_id": "masterkey",
        "master": true
    },
    "cloud_manager": true,
    "db_update": 1,
    "debug": true,
    "file_management": true,
    "polldelay": 0.01,
    "product_build": 2019032301,
    "product_code": "sfa",
    "product_name": "EVA SCADA Final Aggregator",
    "setup_mode": false,
    "system": "mws1-v1",
    "time": 1553393178.4744968,
    "uptime": 2,
    "version": "3.2.0"
}

Parameters:

  • API Key any valid API key

Returns:

JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)

save database and runtime configuration

All modified items, their status, and configuration will be written to the disk. If exec_before_save command is defined in the controller’s configuration file, it’s called before saving and exec_after_save after (e.g. to switch the partition to write mode and back to read-only).

http

POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "save" }

curl

curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "save"}'

wget

wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "save"}'

httpie

echo '{
  "method": "save"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/core', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'save',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with sysfunc=yes permissions

execute a remote system command

Executes a command script on the server where the controller is installed.

http

POST /r/cmd/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "a": "0 2 3", "w": 5, "t": 10 }

curl

curl -i -X POST http://localhost:8812/r/cmd/test -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "0 2 3", "t": 10, "w": 5}'

wget

wget -S -O- http://localhost:8812/r/cmd/test --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"a": "0 2 3", "t": 10, "w": 5}'

httpie

echo '{
  "a": "0 2 3",
  "t": 10,
  "w": 5
}' | http POST http://localhost:8812/r/cmd/test Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/cmd/test', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'a': '0 2 3',
    't': 10,
    'w': 5,
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "args": [
        "0",
        "2",
        "3"
    ],
    "cmd": "test",
    "err": "some text to stderr\n",
    "exitcode": 0,
    "out": "test script start\nparam 1: 0 ( > 0 will generate \"failed\" status)\nparam 2: 2\nparam 3: 3\ndelay 3 sec\nscript finish\n",
    "status": "completed",
    "time": {
        "completed": 1552863480.7081513,
        "created": 1552863480.6993306,
        "running": 1552863480.7001197
    },
    "timeout": 10.0
}

Parameters:

  • API Key API key with allow=cmd permissions

Optionally:

  • a string of command arguments, separated by spaces (passed to the script)
  • w wait (in seconds) before API call sends a response. This allows to try waiting until command finish
  • t maximum time of command execution. If the command fails to finish within the specified time (in sec), it will be terminated

shutdown the controller

Controller process will be exited and then (should be) restarted by watchdog. This allows to restart controller remotely.

http

POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "shutdown" }

curl

curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "shutdown"}'

wget

wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "shutdown"}'

httpie

echo '{
  "method": "shutdown"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/core', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'shutdown',
})

response

HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

switch debugging mode

Enables and disables debugging mode while the controller is running. After the controller is restarted, this parameter is lost and controller switches back to the mode specified in the configuration file.

http

PATCH /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "debug": true }

curl

curl -i -X PATCH http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"debug": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"debug": true}'

httpie

echo '{
  "debug": true
}' | http PATCH http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/core', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'debug': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • debug true for enabling debug mode, false for disabling

log in and get authentication token

Obtains authentication token which can be used in API calls instead of API key.

If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.

If authentication token is specified, the function will check it and return token information if it is valid.

http

POST /r/token HTTP/1.1
Host: localhost:8828
Content-Type: application/json

{ "u": "admin", "p": "123" }

curl

curl -i -X POST http://localhost:8828/r/token -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'

wget

wget -S -O- http://localhost:8828/r/token --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'

httpie

echo '{
  "p": "123",
  "u": "admin"
}' | http POST http://localhost:8828/r/token Content-Type:application/json

python-requests

requests.post('http://localhost:8828/r/token', headers={
    'Content-Type': 'application/json',
}, json={
    'p': '123',
    'u': 'admin',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "key": "masterkey",
    "token": "token:1c166529bc3b06dac6e0fbaefee38ebe77c455480e11ff4431de2b10a5508899",
    "user": "admin"
}

Parameters:

  • API Key valid API key or
  • u user login
  • p user password
  • a authentication token

Returns:

A dict, containing API key ID and authentication token

log out and purge authentication token

Purges authentication token

http

DELETE /r/token HTTP/1.1
Host: localhost:8812
X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7

curl

curl -i -X DELETE http://localhost:8812/r/token -H 'X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/token --header='X-Auth-Key: token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'

httpie

http DELETE http://localhost:8812/r/token X-Auth-Key:token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7

python-requests

requests.delete('http://localhost:8812/r/token', headers={
    'X-Auth-Key': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid token

Item functions

clean action queue of unit

Cancels all queued actions, keeps the current action running.

http

POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "q_clean" }

curl

curl -i -X POST http://localhost:8828/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "q_clean"}'

wget

wget -S -O- http://localhost:8828/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "q_clean"}'

httpie

echo '{
  "method": "q_clean"
}' | http POST http://localhost:8828/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'q_clean',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

create unit control action

The call is considered successful when action is put into the action queue of selected unit.

http

POST /r/action HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "s": 1, "i": "unit:tests/unit3", "s": 1 }

curl

curl -i -X POST http://localhost:8828/r/action -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"i": "unit:tests/unit3", "s": 1}'

wget

wget -S -O- http://localhost:8828/r/action --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"i": "unit:tests/unit3", "s": 1}'

httpie

echo '{
  "i": "unit:tests/unit3",
  "s": 1
}' | http POST http://localhost:8828/r/action Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/action', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'i': 'unit:tests/unit3',
    's': 1,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/751955a9-9eb6-451b-8069-706bd445a9f7
Pragma: no-cache

{
    "err": "",
    "exitcode": null,
    "finished": true,
    "finished_in": 0.0009174,
    "item_group": "tests",
    "item_id": "unit3",
    "item_oid": "unit:tests/unit3",
    "item_type": "unit",
    "nstatus": 1,
    "nvalue": null,
    "out": "",
    "priority": 100,
    "status": "refused",
    "time": {
        "created": 1559868835.769016,
        "pending": 1559868835.769214,
        "refused": 1559868835.7699335
    },
    "uuid": "751955a9-9eb6-451b-8069-706bd445a9f7"
}

Parameters:

  • API Key valid API key

Optionally:

  • s desired unit status
  • v desired unit value
  • w wait for the completion for the specified number of seconds
  • p queue priority (default is 100, lower is better)
  • q global queue timeout, if expires, action is marked as “dead”

Returns:

Serialized action object. If action is marked as dead, an error is returned (exception raised)

disable unit actions

Disables unit to run and queue new actions.

http

PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "action_enabled": false }

curl

curl -i -X PATCH http://localhost:8828/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_enabled": false}'

wget

wget -S -O- --method=PATCH http://localhost:8828/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_enabled": false}'

httpie

echo '{
  "action_enabled": false
}' | http PATCH http://localhost:8828/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8828/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'action_enabled': False,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

enable unit actions

Enables unit to run and queue new actions.

http

PATCH /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "action_enabled": true }

curl

curl -i -X PATCH http://localhost:8828/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"action_enabled": true}'

wget

wget -S -O- --method=PATCH http://localhost:8828/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"action_enabled": true}'

httpie

echo '{
  "action_enabled": true
}' | http PATCH http://localhost:8828/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8828/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'action_enabled': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

get action status or macro run result

Checks the result of the action by its UUID or returns the actions for the specified unit or execution result of the specified macro.

http

GET /r/action?i=unit%3Atests%2Funit1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i 'http://localhost:8828/r/action?i=unit%3Atests%2Funit1' -H 'X-Auth-Key: mykey'

wget

wget -S -O- 'http://localhost:8828/r/action?i=unit%3Atests%2Funit1' --header='X-Auth-Key: mykey'

httpie

http 'http://localhost:8828/r/action?i=unit%3Atests%2Funit1' X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/action?i=unit%3Atests%2Funit1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "err": "",
        "exitcode": null,
        "finished": true,
        "finished_in": 0.0006144,
        "item_group": "tests",
        "item_id": "unit1",
        "item_oid": "unit:tests/unit1",
        "item_type": "unit",
        "nstatus": 1,
        "nvalue": null,
        "out": "",
        "priority": 100,
        "status": "refused",
        "time": {
            "created": 1559868829.0452583,
            "pending": 1559868829.0455182,
            "refused": 1559868829.0458727
        },
        "uuid": "70db470b-7d7e-4698-a001-01958c0ff3a7"
    },
    {
        "err": "",
        "exitcode": null,
        "finished": true,
        "finished_in": 0.0010161,
        "item_group": "tests",
        "item_id": "unit1",
        "item_oid": "unit:tests/unit1",
        "item_type": "unit",
        "nstatus": 1,
        "nvalue": null,
        "out": "",
        "priority": 100,
        "status": "refused",
        "time": {
            "created": 1559868829.087297,
            "pending": 1559868829.0876813,
            "refused": 1559868829.088313
        },
        "uuid": "3737a15b-515c-4e85-be2a-c937392851fa"
    },
    {
        "err": "",
        "exitcode": null,
        "finished": true,
        "finished_in": 0.0005889,
        "item_group": "tests",
        "item_id": "unit1",
        "item_oid": "unit:tests/unit1",
        "item_type": "unit",
        "nstatus": 1,
        "nvalue": null,
        "out": "",
        "priority": 100,
        "status": "refused",
        "time": {
            "created": 1559868835.75104,
            "pending": 1559868835.751197,
            "refused": 1559868835.7516289
        },
        "uuid": "d2aab822-ec47-4370-8145-f8f455db4d27"
    },
    {
        "err": "",
        "exitcode": null,
        "finished": true,
        "finished_in": 0.001091,
        "item_group": "tests",
        "item_id": "unit1",
        "item_oid": "unit:tests/unit1",
        "item_type": "unit",
        "nstatus": 1,
        "nvalue": null,
        "out": "",
        "priority": 100,
        "status": "refused",
        "time": {
            "created": 1559868835.7902575,
            "pending": 1559868835.7906036,
            "refused": 1559868835.7913485
        },
        "uuid": "8038de65-3833-4aa5-94c1-c0f0e86eb3fe"
    }
]

Parameters:

  • API Key valid API key

Optionally:

  • g filter by unit group
  • s filter by action status: Q for queued, R for running, F for finished

Returns:

list or single serialized action object

get item group list

Get the list of item groups. Useful e.g. for custom interfaces.

http

GET /r/unit/@groups HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/unit/@groups -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/unit/@groups --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/unit/@groups X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/unit/@groups', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    "mb",
    "room1",
    "tests"
]

Parameters:

  • API Key valid API key

get item state

State of the item or all items of the specified type can be obtained using state command.

http

GET /r/sensor HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/sensor -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/sensor --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/sensor X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/sensor', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "controller_id": "uc/mws1-v1",
        "full_id": "env/temp_test",
        "group": "env",
        "id": "temp_test",
        "oid": "sensor:env/temp_test",
        "status": 1,
        "type": "sensor",
        "value": "191"
    },
    {
        "controller_id": "uc/mws1-v1",
        "full_id": "room1/lamps",
        "group": "room1",
        "id": "lamps",
        "oid": "sensor:room1/lamps",
        "status": 0,
        "type": "sensor",
        "value": "null"
    },
    {
        "controller_id": "uc/mws1-v1",
        "full_id": "room2/h",
        "group": "room2",
        "id": "h",
        "oid": "sensor:room2/h",
        "status": 0,
        "type": "sensor",
        "value": "null"
    },
    {
        "controller_id": "uc/mws1-v1",
        "full_id": "room2/lamps",
        "group": "room2",
        "id": "lamps",
        "oid": "sensor:room2/lamps",
        "status": 0,
        "type": "sensor",
        "value": "null"
    }
]

Parameters:

  • API Key valid API key

Optionally:

get item state history

State history of one item or several items of the specified type can be obtained using state_history command.

http

GET /r/sensor/env/temp_test@history HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/sensor/env/temp_test@history -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/sensor/env/temp_test@history --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/sensor/env/temp_test@history X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/sensor/env/temp_test@history', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "status": [
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1,
        1
    ],
    "t": [
        1553390125.8643427,
        1553390140.929797,
        1553390334.862889,
        1553390589.4016967,
        1553390732.9677052,
        1553391169.14625,
        1553391188.7430675,
        1553391215.390878,
        1553391623.3912942,
        1553391746.352703,
        1553391851.0065582,
        1553391951.145705,
        1553391968.589165,
        1553392069.766155,
        1553392157.956836,
        1553392366.729588,
        1553392495.9142005,
        1553392581.9080076,
        1553393041.2446685,
        1553393176.3235447
    ],
    "value": [
        19.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0,
        191.0
    ]
}

Parameters:

  • API Key valid API key
  • a history notifier id (default: db_1)

Optionally:

  • s start time (timestamp or ISO or e.g. 1D for -1 day)
  • e end time (timestamp or ISO or e.g. 1D for -1 day)
  • l records limit (doesn’t work with “w”)
  • x state prop (“status” or “value”)
  • t time format(“iso” or “raw” for unix timestamp, default is “raw”)
  • w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified
  • g output format (“list”, “dict” or “chart”, default is “list”)
  • c options for chart (dict or comma separated)

Returns:

history data in specified format or chart image.

For chart, JSON RPC gets reply with “content_type” and “data” fields, where content is image content type. If PNG image format is selected, data is base64-encoded.

Options for chart (all are optional):

If option “w” (fill) is used, number of digits after comma may be specified. E.g. 5T:3 will output values with 3 digits after comma.

Additionally, SI prefix may be specified to convert value to kilos, megas etc, e.g. 5T:k:3 - divide value by 1000 and output 3 digits after comma. Valid prefixes are: k, M, G, T, P, E, Z, Y.

If binary prefix is required, it should be followed by “b”, e.g. 5T:Mb:3 - divide value by 2^20 and output 3 digits after comma.

kill unit actions

Apart from canceling all queued commands, this function also terminates the current running action.

http

POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "kill" }

curl

curl -i -X POST http://localhost:8828/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "kill"}'

wget

wget -S -O- http://localhost:8828/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "kill"}'

httpie

echo '{
  "method": "kill"
}' | http POST http://localhost:8828/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'kill',
})

response

HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

Returns:

If the current action of the unit cannot be terminated by configuration, the notice “pt” = “denied” will be returned additionally (even if there’s no action running)

terminate action execution

Terminates or cancel the action if it is still queued

http

POST /r/unit/tests/unit3 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "terminate" }

curl

curl -i -X POST http://localhost:8828/r/unit/tests/unit3 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "terminate"}'

wget

wget -S -O- http://localhost:8828/r/unit/tests/unit3 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "terminate"}'

httpie

echo '{
  "method": "terminate"
}' | http POST http://localhost:8828/r/unit/tests/unit3 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/unit/tests/unit3', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'terminate',
})

response

HTTP/1.1 202 Accepted
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

Returns:

An error result will be returned eitner if action is terminated (Resource not found) or if termination process is failed or denied by unit configuration (Function failed)

toggle unit status

Create unit control action to toggle its status (1->0, 0->1)

http

POST /r/action HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "i": "unit:tests/unit3", "s": "toggle" }

curl

curl -i -X POST http://localhost:8828/r/action -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"i": "unit:tests/unit3", "s": "toggle"}'

wget

wget -S -O- http://localhost:8828/r/action --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"i": "unit:tests/unit3", "s": "toggle"}'

httpie

echo '{
  "i": "unit:tests/unit3",
  "s": "toggle"
}' | http POST http://localhost:8828/r/action Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/action', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'i': 'unit:tests/unit3',
    's': 'toggle',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/afaab4be-67b5-4906-a32d-1339bcbae5a3
Pragma: no-cache

{
    "err": "",
    "exitcode": null,
    "finished": true,
    "finished_in": 0.0006881,
    "item_group": "tests",
    "item_id": "unit3",
    "item_oid": "unit:tests/unit3",
    "item_type": "unit",
    "nstatus": 1,
    "nvalue": null,
    "out": "",
    "priority": 100,
    "status": "refused",
    "time": {
        "created": 1559868835.8054502,
        "pending": 1559868835.805737,
        "refused": 1559868835.8061383
    },
    "uuid": "afaab4be-67b5-4906-a32d-1339bcbae5a3"
}

Parameters:

  • API Key valid API key

Optionally:

  • w wait for the completion for the specified number of seconds
  • p queue priority (default is 100, lower is better)
  • q global queue timeout, if expires, action is marked as “dead”

Returns:

Serialized action object. If action is marked as dead, an error is returned (exception raised)

clear lvar state

set status (if expires lvar param > 0) or value (if expires isn’t set) of a logic variable to 0. Useful when lvar is used as a timer to stop it, or as a flag to set it False.

http

POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "s": "clear" }

curl

curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": "clear"}'

wget

wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": "clear"}'

httpie

echo '{
  "s": "clear"
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    's': 'clear',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

clear lvar state

set status (if expires lvar param > 0) or value (if expires isn’t set) of a logic variable to 0. Useful when lvar is used as a timer to stop it, or as a flag to set it False.

http

POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "s": "toggle" }

curl

curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": "toggle"}'

wget

wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": "toggle"}'

httpie

echo '{
  "s": "toggle"
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    's': 'toggle',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

reset lvar state

Set status and value of a logic variable to 1. Useful when lvar is being used as a timer to reset it, or as a flag to set it True.

http

POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "s": "reset" }

curl

curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": "reset"}'

wget

wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": "reset"}'

httpie

echo '{
  "s": "reset"
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    's': 'reset',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

set lvar state

Set status and value of a logic variable.

http

POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "s": 1, "v": 29 }

curl

curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"s": 1, "v": 29}'

wget

wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"s": 1, "v": 29}'

httpie

echo '{
  "s": 1,
  "v": 29
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    's': 1,
    'v': 29,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

Optionally:

  • s lvar status
  • v lvar value

LVar functions

decrement lvar value

Decrement value of a logic variable. Initial value should be number

http

POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "v": "!decrement" }

curl

curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "!decrement"}'

wget

wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"v": "!decrement"}'

httpie

echo '{
  "v": "!decrement"
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'v': '!decrement',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

increment lvar value

Increment value of a logic variable. Initial value should be number

http

POST /r/lvar/tests/lvar1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "v": "!increment" }

curl

curl -i -X POST http://localhost:8828/r/lvar/tests/lvar1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "!increment"}'

wget

wget -S -O- http://localhost:8828/r/lvar/tests/lvar1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"v": "!increment"}'

httpie

echo '{
  "v": "!increment"
}' | http POST http://localhost:8828/r/lvar/tests/lvar1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/lvar/tests/lvar1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'v': '!increment',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key valid API key

Logic control macros

execute macro

Execute a macro with the specified arguments.

http

POST /r/lmacro/tests/test1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "run" }

curl

curl -i -X POST http://localhost:8828/r/lmacro/tests/test1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "run"}'

wget

wget -S -O- http://localhost:8828/r/lmacro/tests/test1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "run"}'

httpie

echo '{
  "method": "run"
}' | http POST http://localhost:8828/r/lmacro/tests/test1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/lmacro/tests/test1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'run',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/action/6ea7dc1f-2934-45da-8209-d29d7d1d9259
Pragma: no-cache

{
    "args": [],
    "err": "",
    "exitcode": 0,
    "finished": true,
    "finished_in": 0.0030398,
    "item_group": "tests",
    "item_id": "test1",
    "item_oid": "lmacro:tests/test1",
    "item_type": "lmacro",
    "kwargs": {},
    "out": "",
    "priority": 100,
    "status": "completed",
    "time": {
        "completed": 1559868836.280482,
        "created": 1559868836.2774422,
        "pending": 1559868836.2777095,
        "queued": 1559868836.2782526,
        "running": 1559868836.2789273
    },
    "uuid": "6ea7dc1f-2934-45da-8209-d29d7d1d9259"
}

Parameters:

  • API Key valid API key

Optionally:

  • a macro arguments, array or space separated
  • kw macro keyword arguments, name=value, comma separated or dict
  • w wait for the completion for the specified number of seconds
  • p queue priority (default is 100, lower is better)
  • q global queue timeout, if expires, action is marked as “dead”

get macro groups list

Get the list of macros. Useful e.g. for custom interfaces.

http

GET /r/lmacro/@groups HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/lmacro/@groups -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/lmacro/@groups --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/lmacro/@groups X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/lmacro/@groups', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    "nogroup",
    "tests"
]

Parameters:

  • API Key valid API key

get macro list

Get the list of all available macros.

http

GET /r/lmacro HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/lmacro -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/lmacro --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/lmacro X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/lmacro', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "action_enabled": true,
        "controller_id": "lm/mws1-v1",
        "description": "",
        "full_id": "nogroup/lr",
        "group": "nogroup",
        "id": "lr",
        "oid": "lmacro:nogroup/lr",
        "type": "lmacro"
    },
    {
        "action_enabled": true,
        "controller_id": "lm/mws1-v1",
        "description": "test macro",
        "full_id": "tests/test",
        "group": "tests",
        "id": "test",
        "oid": "lmacro:tests/test",
        "type": "lmacro"
    },
    {
        "action_enabled": true,
        "controller_id": "lm/mws1-v1",
        "description": "",
        "full_id": "tests/test1",
        "group": "tests",
        "id": "test1",
        "oid": "lmacro:tests/test1",
        "type": "lmacro"
    },
    {
        "action_enabled": true,
        "controller_id": "lm/mws1-v1",
        "description": "",
        "full_id": "tests/test2",
        "group": "tests",
        "id": "test2",
        "oid": "lmacro:tests/test2",
        "type": "lmacro"
    }
]

Parameters:

  • API Key valid API key

Optionally:

  • i filter by controller

Logic cycles

get cycle groups list

Get the list of cycles. Useful e.g. for custom interfaces.

http

GET /r/lcycle/@groups HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/lcycle/@groups -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/lcycle/@groups --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/lcycle/@groups X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/lcycle/@groups', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    "tests"
]

Parameters:

  • API Key valid API key

get cycle information

http

GET /r/lcycle/tests/cycle1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/lcycle/tests/cycle1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/lcycle/tests/cycle1 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/lcycle/tests/cycle1 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/lcycle/tests/cycle1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "controller_id": "lm/mws1-v1",
    "description": "",
    "full_id": "tests/cycle1",
    "group": "tests",
    "id": "cycle1",
    "interval": 0.01,
    "oid": "lcycle:tests/cycle1",
    "type": "lcycle"
}

Parameters:

  • API Key valid API key

Returns:

field “value” contains real average cycle interval

get cycle list

Get the list of all available cycles.

http

GET /r/lcycle HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/lcycle -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/lcycle --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/lcycle X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/lcycle', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "controller_id": "lm/mws1-v1",
        "description": "",
        "full_id": "tests/cycle1",
        "group": "tests",
        "id": "cycle1",
        "interval": 0.01,
        "oid": "lcycle:tests/cycle1",
        "status": 0,
        "type": "lcycle",
        "value": "0,0.0100,"
    },
    {
        "controller_id": "lm/mws1-v1",
        "description": "test 2Hz cycle",
        "full_id": "tests/test1",
        "group": "tests",
        "id": "test1",
        "interval": 0.5,
        "oid": "lcycle:tests/test1",
        "status": 0,
        "type": "lcycle",
        "value": "0,0.5000,"
    }
]

Parameters:

  • API Key valid API key

Optionally:

  • i filter by controller

Remote controllers

connect remote controller via HTTP

Connects remote controller to the local.

http

POST /r/controller/uc HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "u": "localhost", "a": "secretkey", "save": true }

curl

curl -i -X POST http://localhost:8828/r/controller/uc -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "secretkey", "save": true, "u": "localhost"}'

wget

wget -S -O- http://localhost:8828/r/controller/uc --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"a": "secretkey", "save": true, "u": "localhost"}'

httpie

echo '{
  "a": "secretkey",
  "save": true,
  "u": "localhost"
}' | http POST http://localhost:8828/r/controller/uc Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/controller/uc', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'a': 'secretkey',
    'save': True,
    'u': 'localhost',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Location: /r/controller/uc/ws1-v1
Pragma: no-cache

{
    "build": "2019031405",
    "connected": true,
    "description": "",
    "enabled": true,
    "full_id": "uc/ws1-v1",
    "group": "uc",
    "id": "ws1-v1",
    "managed": false,
    "mqtt_update": null,
    "oid": "remote_uc:uc/ws1-v1",
    "proto": "http",
    "static": true,
    "type": "remote_uc",
    "version": "3.2.0"
}

Parameters:

  • API Key API key with master permissions
  • u Controller API uri (proto://host:port, port not required if default)
  • a remote controller API key ($key to use local key)

Optionally:

  • m ref:MQTT notifier<mqtt_> to exchange item states in real time (default: eva_1)
  • s verify remote SSL certificate or pass invalid
  • t timeout (seconds) for the remote controller API calls
  • g controller type (“uc” or “lm”), autodetected if none
  • save save connected controller configuration on the disk immediately after creation

disable connected controller

http

PATCH /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "enabled": false }

curl

curl -i -X PATCH http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": false, "save": true}'

wget

wget -S -O- --method=PATCH http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": false, "save": true}'

httpie

echo '{
  "enabled": false,
  "save": true
}' | http PATCH http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8828/r/controller/uc/ws1-v1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'enabled': False,
    'save': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save configuration after successful call

disconnect controller

http

DELETE /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8828/r/controller/uc/ws1-v1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8828/r/controller/uc/ws1-v1 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8828/r/controller/uc/ws1-v1 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8828/r/controller/uc/ws1-v1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

enable connected controller

http

PATCH /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "enabled": true }

curl

curl -i -X PATCH http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": true, "save": true}'

wget

wget -S -O- --method=PATCH http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": true, "save": true}'

httpie

echo '{
  "enabled": true,
  "save": true
}' | http PATCH http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8828/r/controller/uc/ws1-v1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'enabled': True,
    'save': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save configuration after successful call

get a list of items from connected controllers

Get a list of the items loaded from the connected controllers. Useful to debug the controller connections.

http

GET /r/controller/uc/ws1-v1@items HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/controller/uc/ws1-v1@items -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1@items --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/controller/uc/ws1-v1@items X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/controller/uc/ws1-v1@items', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: GET, HEAD, POST
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "controller_id": "uc/ws1-v1",
        "description": "",
        "full_id": "env/temp_test",
        "group": "env",
        "id": "temp_test",
        "loc_x": null,
        "loc_y": null,
        "loc_z": null,
        "location": "",
        "oid": "sensor:env/temp_test",
        "status": 0,
        "type": "sensor",
        "value": "null"
    },
    {
        "action_enabled": true,
        "controller_id": "uc/ws1-v1",
        "description": "",
        "full_id": "nogroup/test2",
        "group": "nogroup",
        "id": "test2",
        "loc_x": null,
        "loc_y": null,
        "loc_z": null,
        "location": "",
        "nstatus": -1,
        "nvalue": "null",
        "oid": "unit:nogroup/test2",
        "status": -1,
        "status_labels": [
            {
                "label": "OFF",
                "status": 0
            },
            {
                "label": "ON",
                "status": 1
            }
        ],
        "type": "unit",
        "value": "null"
    }
]

Parameters:

  • API Key API key with master permissions

Optionally:

  • g filter by item group
  • p filter by item type

get connected controller information

http

GET /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/controller/uc/ws1-v1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/controller/uc/ws1-v1 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/controller/uc/ws1-v1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "build": "2019031405",
    "connected": true,
    "description": "",
    "enabled": true,
    "full_id": "uc/ws1-v1",
    "group": "uc",
    "id": "ws1-v1",
    "managed": false,
    "mqtt_update": null,
    "oid": "remote_uc:uc/ws1-v1",
    "proto": "http",
    "static": true,
    "type": "remote_uc",
    "version": "3.2.0"
}

Parameters:

  • API Key API key with master permissions

get controller connection parameters

http

GET /r/controller/uc/ws1-v1@props HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/controller/uc/ws1-v1@props -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1@props --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/controller/uc/ws1-v1@props X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/controller/uc/ws1-v1@props', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "description": "",
    "enabled": true,
    "key": "secretkey",
    "mqtt_update": null,
    "reload_interval": 300,
    "retries": 2,
    "ssl_verify": true,
    "static": true,
    "timeout": 5.0,
    "uri": "http://localhost:8812"
}

Parameters:

  • API Key API key with master permissions

get controllers list

Get the list of all connected controllers.

http

GET /r/controller HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i http://localhost:8828/r/controller -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8828/r/controller --header='X-Auth-Key: mykey'

httpie

http http://localhost:8828/r/controller X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8828/r/controller', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "build": "2019032301",
        "connected": true,
        "description": "",
        "enabled": true,
        "full_id": "lm/mws1-v1",
        "group": "lm",
        "id": "mws1-v1",
        "managed": false,
        "mqtt_update": "eva_1",
        "oid": "remote_lm:lm/mws1-v1",
        "proto": "http",
        "static": true,
        "type": "remote_lm",
        "version": "3.2.0"
    },
    {
        "build": "2019032301",
        "connected": true,
        "description": "",
        "enabled": true,
        "full_id": "uc/mws1-v1",
        "group": "uc",
        "id": "mws1-v1",
        "managed": false,
        "mqtt_update": "eva_1",
        "oid": "remote_uc:uc/mws1-v1",
        "proto": "http",
        "static": true,
        "type": "remote_uc",
        "version": "3.2.0"
    }
]

Parameters:

  • API Key API key with master permissions

reload controller

Reloads items from connected controller. If controller ID “ALL” is specified, all connected controllers are reloaded.

http

POST /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "reload" }

curl

curl -i -X POST http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "reload"}'

wget

wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "reload"}'

httpie

echo '{
  "method": "reload"
}' | http POST http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/controller/uc/ws1-v1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'reload',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

set controller connection parameters

http

PATCH /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "reload_interval": 60 }

curl

curl -i -X PATCH http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"reload_interval": 60, "save": true}'

wget

wget -S -O- --method=PATCH http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"reload_interval": 60, "save": true}'

httpie

echo '{
  "reload_interval": 60,
  "save": true
}' | http PATCH http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8828/r/controller/uc/ws1-v1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'reload_interval': 60,
    'save': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save configuration after successful call

test connection to remote controller

http

POST /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "test" }

curl

curl -i -X POST http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "test"}'

wget

wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "test"}'

httpie

echo '{
  "method": "test"
}' | http POST http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/controller/uc/ws1-v1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'test',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

test management API connection to remote controller

http

POST /r/controller/uc/ws1-v1 HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "matest" }

curl

curl -i -X POST http://localhost:8828/r/controller/uc/ws1-v1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "matest"}'

wget

wget -S -O- http://localhost:8828/r/controller/uc/ws1-v1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "matest"}'

httpie

echo '{
  "method": "matest"
}' | http POST http://localhost:8828/r/controller/uc/ws1-v1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/controller/uc/ws1-v1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'matest',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

Connected clients

ask connected clients to reload

Sends reload event to all connected clients asking them to reload the interface.

All the connected clients receive the event with subject=”reload” and data=”asap”. If the clients use EVA JS Framework, they can catch server.reload event.

http

POST /r/core HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "reload_clients" }

curl

curl -i -X POST http://localhost:8828/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "reload_clients"}'

wget

wget -S -O- http://localhost:8828/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "reload_clients"}'

httpie

echo '{
  "method": "reload_clients"
}' | http POST http://localhost:8828/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/core', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'reload_clients',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

notify connected clients about server restart

Sends a server restart event to all connected clients asking them to prepare for server restart.

All the connected clients receive the event with subject=”server” and data=”restart”. If the clients use EVA JS Framework, they can catch server.restart event.

Server restart notification is sent automatically to all connected clients when the server is restarting. This API function allows to send server restart notification without actual server restart, which may be useful e.g. for testing, handling frontend restart etc.

http

POST /r/core HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "notify_restart" }

curl

curl -i -X POST http://localhost:8828/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "notify_restart"}'

wget

wget -S -O- http://localhost:8828/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "notify_restart"}'

httpie

echo '{
  "method": "notify_restart"
}' | http POST http://localhost:8828/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/core', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'notify_restart',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

CVARs

get the value of user-defined variable

Note

Even if different EVA controllers are working on the same server, they have different sets of variables To set the variables for each subsystem, use SYS API on the respective address/port.

http

GET /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/cvar/test -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/cvar/test --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/cvar/test X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/cvar/test', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "test": "some_value"
}

Parameters:

  • API Key API key with master permissions

Optionally:

Returns:

Dict containing variable and its value. If no varible name was specified, all cvars are returned.

set the value of user-defined variable

http

PUT /r/cvar/test HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "v": "some_value" }

curl

curl -i -X PUT http://localhost:8812/r/cvar/test -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"v": "some_value"}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/cvar/test --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"v": "some_value"}'

httpie

echo '{
  "v": "some_value"
}' | http PUT http://localhost:8812/r/cvar/test Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/cvar/test', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'v': 'some_value',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "test": "some_value"
}

Parameters:

  • API Key API key with master permissions

Optionally:

  • v variable value (if not specified, variable is deleted)

Locking functions

acquire lock

Locks can be used similarly to file locking by the specific process. The difference is that SYS API tokens can be:

  • centralized for several systems (any EVA server can act as lock server)
  • removed from outside
  • automatically unlocked after the expiration time, if the initiator failed or forgot to release the lock

used to restrict parallel process starting or access to system files/resources. LM PLC macro share locks with extrnal scripts.

Note

Even if different EVA controllers are working on the same server, their lock tokens are stored in different bases. To work with the token of each subsystem, use SYS API on the respective address/port.

http

PUT /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "e": 1, "t": 15 }

curl

curl -i -X PUT http://localhost:8812/r/lock/mylock1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": 1, "t": 15}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/lock/mylock1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": 1, "t": 15}'

httpie

echo '{
  "e": 1,
  "t": 15
}' | http PUT http://localhost:8812/r/lock/mylock1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/lock/mylock1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'e': 1,
    't': 15,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": "mylock1",
    "type": "lock"
}

Parameters:

  • API Key API key with allow=lock permissions

Optionally:

  • t maximum time (seconds) to acquire lock
  • e time after which lock is automatically released (if absent, lock may be released only via unlock function)

get lock status

http

GET /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/lock/mylock1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/lock/mylock1 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/lock/mylock1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": "mylock1",
    "locked": true,
    "type": "lock"
}

Parameters:

  • API Key API key with allow=lock permissions

release lock

Releases the previously acquired lock.

http

DELETE /r/lock/mylock1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/lock/mylock1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/lock/mylock1 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/lock/mylock1 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/lock/mylock1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with allow=lock permissions

Logging

put message to log file

An external application can put a message in the logs on behalf of the controller.

http

POST /r/log/warning HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "m": "local file system is full" }

curl

curl -i -X POST http://localhost:8812/r/log/warning -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"m": "local file system is full"}'

wget

wget -S -O- http://localhost:8812/r/log/warning --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"m": "local file system is full"}'

httpie

echo '{
  "m": "local file system is full"
}' | http POST http://localhost:8812/r/log/warning Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/log/warning', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'm': 'local file system is full',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with sysfunc=yes permissions
  • l log level
  • m message text

put debug message to log file

An external application can put a message in the logs on behalf of the controller.

Parameters:

  • API Key API key with sysfunc=yes permissions
  • m message text

put info message to log file

An external application can put a message in the logs on behalf of the controller.

Parameters:

  • API Key API key with sysfunc=yes permissions
  • m message text

put warning message to log file

An external application can put a message in the logs on behalf of the controller.

Parameters:

  • API Key API key with sysfunc=yes permissions
  • m message text

put error message to log file

An external application can put a message in the logs on behalf of the controller.

Parameters:

  • API Key API key with sysfunc=yes permissions
  • m message text

put critical message to log file

An external application can put a message in the logs on behalf of the controller.

Parameters:

  • API Key API key with sysfunc=yes permissions
  • m message text

get records from the controller log

Log records are stored in the controllers’ memory until restart or the time (keep_logmem) specified in controller configuration passes.

http

GET /r/log/warning?t=3600&n=3 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i 'http://localhost:8812/r/log/warning?t=3600&n=3' -H 'X-Auth-Key: mykey'

wget

wget -S -O- 'http://localhost:8812/r/log/warning?t=3600&n=3' --header='X-Auth-Key: mykey'

httpie

http 'http://localhost:8812/r/log/warning?t=3600&n=3' X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/log/warning?t=3600&n=3', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "h": "mws1-v1",
        "l": 30,
        "mod": "sysapi",
        "msg": "test warning message",
        "p": "uc",
        "t": 1552863481.1394246,
        "th": "CP Server Thread-15"
    },
    {
        "h": "mws1-v1",
        "l": 40,
        "mod": "sysapi",
        "msg": "test error message",
        "p": "uc",
        "t": 1552863481.1516943,
        "th": "CP Server Thread-16"
    },
    {
        "h": "mws1-v1",
        "l": 50,
        "mod": "sysapi",
        "msg": "test critical message",
        "p": "uc",
        "t": 1552863481.1631815,
        "th": "CP Server Thread-17"
    }
]

Parameters:

  • API Key API key with sysfunc=yes permissions

Optionally:

  • t get log records not older than t seconds
  • n the maximum number of log records you want to obtain

rotate log file

Equal to kill -HUP <controller_process_pid>.

http

POST /r/core HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "log_rotate" }

curl

curl -i -X POST http://localhost:8812/r/core -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "log_rotate"}'

wget

wget -S -O- http://localhost:8812/r/core --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "log_rotate"}'

httpie

echo '{
  "method": "log_rotate"
}' | http POST http://localhost:8812/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/core', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'log_rotate',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with sysfunc=yes permissions

API keys

create API key

API keys are defined statically in etc/<controller>_apikeys.ini file as well as can be created with API and stored in user database.

Keys with master permission can not be created.

http

PUT /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "sysfunc": true, "allow": "cmd" }

curl

curl -i -X PUT http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"allow": "cmd", "save": true, "sysfunc": true}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"allow": "cmd", "save": true, "sysfunc": true}'

httpie

echo '{
  "allow": "cmd",
  "save": true,
  "sysfunc": true
}' | http PUT http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/key/testkey2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'allow': 'cmd',
    'save': True,
    'sysfunc': True,
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "allow": [
        "cmd"
    ],
    "dynamic": true,
    "groups": [],
    "hosts_allow": [
        "0.0.0.0/0"
    ],
    "hosts_assign": [],
    "id": "testkey2",
    "items": [],
    "key": "443e342f7e49566fafc1cbe928878b0c18510bb2979ceca7aceb5e45b2b96280",
    "master": false,
    "pvt": [],
    "rpvt": [],
    "sysfunc": true
}

Parameters:

  • API Key API key with master permissions
  • save save configuration immediately

Returns:

JSON with serialized key object

delete API key

http

DELETE /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/key/testkey2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/key/testkey2 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/key/testkey2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

list API key permissions

Lists API key permissons (including a key itself)

Note

API keys, defined in etc/<controller>_apikeys.ini file can not be managed with API.

http

GET /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/key/testkey2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/key/testkey2 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/key/testkey2 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/key/testkey2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "allow": [
        "cmd"
    ],
    "dynamic": true,
    "groups": [],
    "hosts_allow": [
        "0.0.0.0/0"
    ],
    "hosts_assign": [],
    "id": "testkey2",
    "items": [],
    "key": "443e342f7e49566fafc1cbe928878b0c18510bb2979ceca7aceb5e45b2b96280",
    "master": false,
    "pvt": [],
    "rpvt": [],
    "sysfunc": true
}

Parameters:

  • API Key API key with master permissions
  • save save configuration immediately

list API keys

http

GET /r/key HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/key -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/key --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/key X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/key', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "dynamic": false,
        "key_id": "masterkey",
        "master": true
    },
    {
        "allow": {
            "cmd": true,
            "device": true,
            "lock": false
        },
        "dynamic": true,
        "groups": [
            "#"
        ],
        "items": [],
        "key_id": "default",
        "master": false,
        "sysfunc": false
    },
    {
        "allow": {
            "cmd": true,
            "device": true,
            "lock": false
        },
        "dynamic": false,
        "groups": [
            "#"
        ],
        "items": [],
        "key_id": "lm",
        "master": false,
        "sysfunc": false
    },
    {
        "allow": {
            "cmd": false,
            "device": true,
            "lock": true
        },
        "dynamic": false,
        "groups": [
            "#"
        ],
        "items": [],
        "key_id": "operator",
        "master": false,
        "sysfunc": true
    },
    {
        "allow": {
            "cmd": false,
            "device": false,
            "lock": false
        },
        "dynamic": false,
        "groups": [
            "#"
        ],
        "items": [],
        "key_id": "sfa",
        "master": false,
        "sysfunc": false
    },
    {
        "allow": {
            "cmd": false,
            "device": false,
            "lock": false
        },
        "dynamic": true,
        "groups": [],
        "items": [
            "item1"
        ],
        "key_id": "t4",
        "master": false,
        "sysfunc": true
    },
    {
        "allow": {
            "cmd": false,
            "device": false,
            "lock": false
        },
        "dynamic": false,
        "groups": [],
        "items": [
            "sensor:sensors/sensor1"
        ],
        "key_id": "test",
        "master": false,
        "sysfunc": false
    },
    {
        "allow": {
            "cmd": false,
            "device": false,
            "lock": false
        },
        "dynamic": true,
        "groups": [],
        "items": [],
        "key_id": "testkey",
        "master": false,
        "sysfunc": true
    },
    {
        "allow": {
            "cmd": true,
            "device": false,
            "lock": false
        },
        "dynamic": true,
        "groups": [],
        "items": [],
        "key_id": "testkey2",
        "master": false,
        "sysfunc": true
    }
]

Parameters:

  • API Key API key with master permissions

regenerate API key

http

POST /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "method": "regenerate" }

curl

curl -i -X POST http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"method": "regenerate"}'

wget

wget -S -O- http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --post-data='{"method": "regenerate"}'

httpie

echo '{
  "method": "regenerate"
}' | http POST http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/key/testkey2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'method': 'regenerate',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "key": "3dbcd3d24c6dc878cebe369eb9fdb95ae99fee14e99cdfd911b83629688d2854"
}

Parameters:

  • API Key API key with master permissions

Returns:

JSON dict with new key value in “key” field

set API key permissions

http

PATCH /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "save": true, "sysfunc": true }

curl

curl -i -X PATCH http://localhost:8812/r/key/testkey2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"save": true, "sysfunc": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/key/testkey2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"save": true, "sysfunc": true}'

httpie

echo '{
  "save": true,
  "sysfunc": true
}' | http PATCH http://localhost:8812/r/key/testkey2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/key/testkey2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'save': True,
    'sysfunc': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • p property
  • v value (if none, permission will be revoked)
  • save save configuration immediately

User accounts

assign API key to user

http

PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "a": "masterkey" }

curl

curl -i -X PATCH http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "masterkey"}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"a": "masterkey"}'

httpie

echo '{
  "a": "masterkey"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/user/test2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'a': 'masterkey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • a API key to assign (key id, not a key itself)

create user account

Note

All changes to user accounts are instant, if the system works in read/only mode, set it to read/write before performing user management.

http

PUT /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "p": "verysecretpassword", "a": "testkey" }

curl

curl -i -X PUT http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"a": "testkey", "p": "verysecretpassword"}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"a": "testkey", "p": "verysecretpassword"}'

httpie

echo '{
  "a": "testkey",
  "p": "verysecretpassword"
}' | http PUT http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/user/test2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'a': 'testkey',
    'p': 'verysecretpassword',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "key": "testkey",
    "user": "test2"
}

Parameters:

  • API Key API key with master permissions
  • p user password
  • a API key to assign (key id, not a key itself)

delete user account

http

DELETE /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/user/test2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/user/test2 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/user/test2 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/user/test2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

get user account info

http

GET /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/user/test2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/user/test2 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/user/test2 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/user/test2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "key": "testkey",
    "user": "test2"
}

Parameters:

  • API Key API key with master permissions

list user accounts

http

GET /r/user HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/user -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/user --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/user X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/user', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "key": "test",
        "user": "divisor"
    },
    {
        "key": "testkey",
        "user": "test"
    },
    {
        "key": "testkey",
        "user": "test2"
    }
]

Parameters:

  • API Key API key with master permissions

set user password

http

PATCH /r/user/test2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "p": "qwerty" }

curl

curl -i -X PATCH http://localhost:8812/r/user/test2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"p": "qwerty"}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/user/test2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"p": "qwerty"}'

httpie

echo '{
  "p": "qwerty"
}' | http PATCH http://localhost:8812/r/user/test2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/user/test2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'p': 'qwerty',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • p new password

Notifier management

disable notifier

Note

The notifier is disabled until controller restart. To disable notifier permanently, use notifier management CLI.

http

PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "enabled": false }

curl

curl -i -X PATCH http://localhost:8812/r/notifier/eva_1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": false}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/notifier/eva_1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": false}'

httpie

echo '{
  "enabled": false
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/notifier/eva_1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'enabled': False,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

enable notifier

Note

The notifier is enabled until controller restart. To enable notifier permanently, use notifier management CLI.

http

PATCH /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "enabled": true }

curl

curl -i -X PATCH http://localhost:8812/r/notifier/eva_1 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"enabled": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/notifier/eva_1 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"enabled": true}'

httpie

echo '{
  "enabled": true
}' | http PATCH http://localhost:8812/r/notifier/eva_1 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/notifier/eva_1', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'enabled': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

get notifier configuration

http

GET /r/notifier/eva_1 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/notifier/eva_1 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/notifier/eva_1 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/notifier/eva_1 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/notifier/eva_1', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "announce_interval": 5.0,
    "api_enabled": true,
    "enabled": false,
    "events": [
        {
            "groups": [
                "#"
            ],
            "subject": "state",
            "types": [
                "#"
            ]
        },
        {
            "level": 30,
            "subject": "log"
        }
    ],
    "host": "mws1-v1",
    "id": "eva_1",
    "password": "test",
    "qos": {
        "action": 2,
        "log": 2,
        "state": 2,
        "system": 2
    },
    "type": "mqtt",
    "username": "eva"
}

Parameters:

  • API Key API key with master permissions

list notifiers

http

GET /r/notifier HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/notifier -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/notifier --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/notifier X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/notifier', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

[
    {
        "db": "db1.db",
        "enabled": true,
        "events": [
            {
                "groups": [
                    "#"
                ],
                "subject": "state",
                "types": [
                    "#"
                ]
            }
        ],
        "id": "db_1",
        "keep": 86400,
        "type": "db"
    },
    {
        "announce_interval": 5.0,
        "api_enabled": true,
        "enabled": false,
        "events": [
            {
                "groups": [
                    "#"
                ],
                "subject": "state",
                "types": [
                    "#"
                ]
            },
            {
                "level": 30,
                "subject": "log"
            }
        ],
        "host": "mws1-v1",
        "id": "eva_1",
        "password": "test",
        "qos": {
            "action": 2,
            "log": 2,
            "state": 2,
            "system": 2
        },
        "type": "mqtt",
        "username": "eva"
    }
]

Parameters:

  • API Key API key with master permissions

File management

put file to runtime folder

Puts a new file into runtime folder. If the file with such name exists, it will be overwritten. As all files in runtime are text, binary data can not be put.

http

PUT /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "m": "/bin/sh\n\nexit 0", "e": true }

curl

curl -i -X PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": true, "m": "/bin/sh\n\nexit 0"}'

wget

wget -S -O- --method=PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": true, "m": "/bin/sh\n\nexit 0"}'

httpie

echo '{
  "e": true,
  "m": "/bin/sh\n\nexit 0"
}' | http PUT http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.put('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'e': True,
    'm': '/bin/sh\n\nexit 0',
})

response

HTTP/1.1 201 Created
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": "xc/uc/test_action_script2",
    "type": "runtime"
}

Parameters:

  • API Key API key with master permissions
  • m file content

set file exec permission

http

PATCH /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json

{ "e": true, "e": true }

curl

curl -i -X PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'Content-Type: application/json' -H 'X-Auth-Key: mykey' --data-raw '{"e": true}'

wget

wget -S -O- --method=PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='Content-Type: application/json' --header='X-Auth-Key: mykey' --body-data='{"e": true}'

httpie

echo '{
  "e": true
}' | http PATCH http://localhost:8812/r/runtime/xc/uc/test_action_script2 Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.patch('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
    'Content-Type': 'application/json',
    'X-Auth-Key': 'mykey',
}, json={
    'e': True,
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions
  • e false for 0x644, true for 0x755 (executable)

delete file from runtime folder

http

DELETE /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- --method=DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='X-Auth-Key: mykey'

httpie

http DELETE http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey

python-requests

requests.delete('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 204 No Content
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Expires: 0
Pragma: no-cache

Parameters:

  • API Key API key with master permissions

get file contents from runtime folder

http

GET /r/runtime/xc/uc/test_action_script2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i http://localhost:8812/r/runtime/xc/uc/test_action_script2 -H 'X-Auth-Key: mykey'

wget

wget -S -O- http://localhost:8812/r/runtime/xc/uc/test_action_script2 --header='X-Auth-Key: mykey'

httpie

http http://localhost:8812/r/runtime/xc/uc/test_action_script2 X-Auth-Key:mykey

python-requests

requests.get('http://localhost:8812/r/runtime/xc/uc/test_action_script2', headers={
    'X-Auth-Key': 'mykey',
})

response

HTTP/1.1 200 OK
Allow: DELETE, GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "data": "/bin/sh\n\nexit 0",
    "e": true,
    "file": "xc/uc/test_action_script2"
}

Parameters:

  • API Key API key with master permissions