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 see SFA API.
RESTful API basics
Warning
RESTful API is deprecated and scheduled to be removed (not implemented) in EVA ICS v4. Use JSON RPC API, whenever it is possible.
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.
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.
Long API calls
Long API calls should be avoided at any cost.
All critical action and command methods have an option to obtain action ID and check for the result later.
If long API calls are performed between controllers (e.g. action methods with wait param), remote controller timeout should be always greater than max. expected “wait” timeout in API call, otherwise client controller will repeat API calls continuously, up to max retries for the target controller.
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.
The result section “controllers” contains connection status of remote controllers. The API key must have an access either to “uc” and “lm” groups (“remote_uc:uc” and “remote_lm:lm”) or to particular controller oids.
http
GET /r/core HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i -X GET 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
Clear language cache
check access to the particular item
Does not check is supervisor lock set, also does not check the item really exist
Parameters:
API Key valid API key
i item id or list of ids
Returns:
oid list with subobjects “r”, “w” (true/false)
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) or array (list)
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
s STDIN data
get list of loaded core plugins
http
GET /r/plugin HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X GET http://localhost:8812/r/plugin -H "X-Auth-Key: mykey"
wget
wget -S -O- http://localhost:8812/r/plugin --header="X-Auth-Key: mykey"
httpie
http http://localhost:8812/r/plugin X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/plugin', 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
[
{
"author": "Altertech, https://www.altertech.com/",
"license": "Apache License 2.0",
"name": "test",
"version": "0.0.1"
}
]
Parameters:
API Key API key with master permissions
Returns:
list with plugin module information
install a package
Parameters:
API Key API key with master permissions
m package content (base64-encoded tar/tgz)
o package setup options
w wait (in seconds) before API call sends a response. This allows to try waiting until the package is installed
shutdown the controller
Controller process will be exited and then (should be) restarted by watchdog. This allows to restart controller remotely.
For MQTT API calls a small shutdown delay usually should be specified to let the core send the correct API response.
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
Returns:
current boot id. This allows client to check is the controller restarted later, by comparing returned boot id and new boot id (obtained with “test” command)
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 an 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.
If both token and credentials (user or API key) are specified, the function will return the token to normal mode.
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 the 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
Set token read-only
Applies read-only mode for token. In read-only mode, only read-only functions work, others return result_token_restricted(15).
The method works for token-authenticated API calls only.
To exit read-only mode, user must either re-login or, to keep the current token, call “login” API method with both token and user credentials.
Get neighbor clients
Parameters:
API Key valid API key
i neightbor client id
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 -X GET '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, D for dead
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 -X GET 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 -X GET 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.
If master key is used, the method attempts to get stored state for an item even if it doesn’t present currently in system.
The method can return state log for disconnected items as well.
http
GET /r/sensor/env/temp_test@history HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i -X GET 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”)
z Time zone (pytz, e.g. UTC or Europe/Prague)
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)
o extra options for notifier data request
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):
type: chart type (line or bar, default is line)
tf: chart time format
out: output format (svg, png, default is svg),
style: chart style (without “Style” suffix, e.g. Dark)
other options: http://pygal.org/en/stable/documentation/configuration/chart.html#options (use range_min, range_max for range, other are passed as-is)
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.
get item state log
State log of a single item or group of the specified type can be obtained using state_log command.
note: only SQL notifiers are supported
Difference from state_history method:
state_log doesn’t optimize data to be displayed on charts * the data is returned from a database as-is * a single item OID or OID mask (e.g. sensor:env/#) can be specified
note: the method supports MQTT-style masks but only masks with wildcard-ending, like “type:group/subgroup/#” are supported.
The method can return state log for disconnected items as well.
For wildcard fetching, API key should have an access to the whole chosen group.
note: record limit means the limit for records, fetched from the database, but repeating state records are automatically grouped and the actual number of returned records can be lower than requested.
http
GET /r/sensor/tests/test1@log HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
curl
curl -i -X GET http://localhost:8828/r/sensor/tests/test1@log -H "X-Auth-Key: mykey"
wget
wget -S -O- http://localhost:8828/r/sensor/tests/test1@log --header="X-Auth-Key: mykey"
httpie
http http://localhost:8828/r/sensor/tests/test1@log X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8828/r/sensor/tests/test1@log', 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
[
{
"oid": "sensor:tests/test1",
"status": 1,
"t": 1607295696.9975107,
"value": 359.0
},
{
"oid": "sensor:tests/test1",
"status": 1,
"t": 1607295713.5487244,
"value": 772.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”)
t time format (“iso” or “raw” for unix timestamp, default is “raw”)
z Time zone (pytz, e.g. UTC or Europe/Prague)
o extra options for notifier data request
Returns:
state log records (list)
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
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
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
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 -X GET 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 -X GET 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 -X GET 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
Logic 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 -X GET 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 -X GET 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
Supervisor functions
set supervisor API lock
When supervisor lock is set, SFA API functions become read-only for all users, except users in the lock scope.
http
PATCH /r/core HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "supervisor_lock": {} }
curl
curl -i -X PATCH http://localhost:8828/r/core -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"supervisor_lock": {}}'
wget
wget -S -O- --method=PATCH http://localhost:8828/r/core --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --body-data='{"supervisor_lock": {}}'
httpie
echo '{
"supervisor_lock": {}
}' | http PATCH http://localhost:8828/r/core Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.patch('http://localhost:8828/r/core', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'supervisor_lock': {}})
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=supervisor permissions
Notes:
supervisor_lock should be a dictionary. If the dictionary is empty, default lock is set.
attribute “l” = “<k|u>” sets lock scope (key / user)
attribute “c” = “<k|u>” set unlock/override scope
attribute “o” overrides lock owner (master key is required) with sub-attributes:
“u” = user
“utp” = user type (null for local, “msad” for Active Directory etc.)
“key_id” = API key ID
clear supervisor API lock
API key should have permission to clear existing supervisor lock
Parameters:
API Key API key with allow=supervisor permissions
Returns:
Successful result is returned if lock is either cleared or not set
send broadcast message
http
POST /r/core HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "m": "hello this is a test", "method": "supervisor_message" }
curl
curl -i -X POST http://localhost:8828/r/core -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"m": "hello this is a test", "method": "supervisor_message"}'
wget
wget -S -O- http://localhost:8828/r/core --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"m": "hello this is a test", "method": "supervisor_message"}'
httpie
echo '{
"m": "hello this is a test",
"method": "supervisor_message"
}' | 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={'m': 'hello this is a test', 'method': 'supervisor_message'})
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=supervisor permissions
m message text
Notes:
If master key is used, sender can be overriden with “sender” argument, which should be a dictionary and contain:
u = message sender user
key_id = message sender API key ID
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 -X GET 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 -X GET 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 -X GET 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 -X GET 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
rescan controllers via UPnP
http
POST /r/controller HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "upnp-rescan" }
curl
curl -i -X POST http://localhost:8828/r/controller -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "upnp-rescan"}'
wget
wget -S -O- http://localhost:8828/r/controller --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "upnp-rescan"}'
httpie
echo '{
"method": "upnp-rescan"
}' | http POST http://localhost:8828/r/controller Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8828/r/controller', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'upnp-rescan'})
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 ICS 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 ICS 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 -X GET 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 can 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 -X GET 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 -X GET '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
x regex pattern filter
rotate log file
Deprecated, not required since 3.3.0
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
get API call log
API call with master permission returns all records requested
API call with other API key returns records for the specified key only
API call with an authentication token returns records for the current authorized user
http
GET /r/core@apilog HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X GET http://localhost:8812/r/core@apilog -H "X-Auth-Key: mykey"
wget
wget -S -O- http://localhost:8812/r/core@apilog --header="X-Auth-Key: mykey"
httpie
http http://localhost:8812/r/core@apilog X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/core@apilog', 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
[
{
"auth": "key",
"func": "login",
"gw": "http",
"id": "a4ac6da7-2fa8-4938-8613-48e6495158b1",
"ip": "127.0.0.1",
"ki": "operator",
"params": "{\"u\":\"ttt\",\"p\":\"<hidden>\"}",
"status": "OK",
"t": 1596055098.3651853,
"tf": 1596055098.3837607,
"u": "ttt",
"utp": null
},
{
"auth": "key",
"func": "list_key_props",
"gw": "http",
"id": "35685960-cc2f-4fb6-8efc-c4ebca8bf9b5",
"ip": "127.0.0.1",
"ki": "masterkey",
"params": "{\"i\":\"operator\"}",
"status": "OK",
"t": 1596055125.9569867,
"tf": 1596055125.9690392,
"u": null,
"utp": null
},
{
"auth": "key",
"func": "action_toggle",
"gw": "http",
"id": "1bdc23da-95a1-4b41-b354-3f3c62e24405",
"ip": "127.0.0.1",
"ki": "masterkey",
"params": "{\"i\":\"unit:light/hall\",\"p\":null,\"w\":null,\"q\":null,\"u\":null}",
"status": "OK",
"t": 1596055185.7343063,
"tf": 1596055185.7551231,
"u": null,
"utp": null
}
]
Parameters:
API Key any valid API key
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)
n records limit
t time format (“iso” or “raw” for unix timestamp, default is “raw”)
f record filter (requires API key with master permission)
Returns:
List of API calls
Note: API call params are returned as string and can be invalid JSON data as they’re always truncated to 512 symbols in log database
Record filter should be specified either as string (k1=val1,k2=val2) or as a dict. Valid fields are:
gw: filter by API gateway
ip: filter by caller IP
auth: filter by authentication type
u: filter by user
utp: filter by user type
ki: filter by API key ID
func: filter by API function
params: filter by API call params (matches if field contains value)
status: filter by API call status
API keys
create API key
API keys are defined statically in EVA registry config/<controller>/apikeys tree or can be created with API and stored in the user database.
Keys with the 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 EVA registry can not be managed with API.
http
GET /r/key/testkey2 HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X GET 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 -X GET 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) or multiple keys, comma separated
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 -X GET 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 -X GET 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_id": "test",
"user": "divisor"
},
{
"key_id": "testkey",
"user": "test"
},
{
"key_id": "testkey",
"user": "test2"
}
]
Parameters:
API Key API key with master permissions
set user password
Either master key and user login must be specified or a user must be logged in and a session token used
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 master key or token
p new password
List active session tokens
Parameters:
API Key API key with master permissions
Drop session token(s)
Parameters:
API Key API key with master permissions
a session token or
u user name or
i API key id
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 -X GET 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 -X GET 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
restart notifier
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 (plain text or base64-encoded)
b if True - put binary file (decode base64)
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 -X GET 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
b if True - force getting binary file (base64-encode content)
Core scripts
List MQTT topics core scripts react on
http
GET /r/corescript/mqtt-topics HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
curl
curl -i -X GET http://localhost:8812/r/corescript/mqtt-topics -H "X-Auth-Key: mykey"
wget
wget -S -O- http://localhost:8812/r/corescript/mqtt-topics --header="X-Auth-Key: mykey"
httpie
http http://localhost:8812/r/corescript/mqtt-topics X-Auth-Key:mykey
python-requests
requests.get('http://localhost:8812/r/corescript/mqtt-topics', 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
[
{
"qos": 2,
"topic": "eva_1:cluster/#"
},
{
"qos": 2,
"topic": "test/test2"
},
{
"qos": 1,
"topic": "ttt/ttt"
}
]
Parameters:
API Key API key with master permissions
Reload core scripts if some was added or deleted
http
POST /r/corescript HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "reload" }
curl
curl -i -X POST http://localhost:8812/r/corescript -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "reload"}'
wget
wget -S -O- http://localhost:8812/r/corescript --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "reload"}'
httpie
echo '{
"method": "reload"
}' | http POST http://localhost:8812/r/corescript Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/corescript', 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
Subscribe core scripts to MQTT topic
The method subscribes core scripts to topic of default MQTT notifier (eva_1). To specify another notifier, set topic as <notifer_id>:<topic>
http
POST /r/corescript HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "q": 2, "method": "mqtt-subscribe", "t": "some/test/topic2" }
curl
curl -i -X POST http://localhost:8812/r/corescript -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "mqtt-subscribe", "q": 2, "t": "some/test/topic2"}'
wget
wget -S -O- http://localhost:8812/r/corescript --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "mqtt-subscribe", "q": 2, "t": "some/test/topic2"}'
httpie
echo '{
"method": "mqtt-subscribe",
"q": 2,
"t": "some/test/topic2"
}' | http POST http://localhost:8812/r/corescript Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/corescript', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'mqtt-subscribe', 'q': 2, 't': 'some/test/topic2'})
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
t MQTT topic (“+” and “#” masks are supported)
q MQTT topic QoS
save save core script config after modification
Unsubscribe core scripts from MQTT topic
http
POST /r/corescript HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey
Content-Type: application/json
{ "method": "mqtt-unsubscribe", "t": "some/test/topic2" }
curl
curl -i -X POST http://localhost:8812/r/corescript -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "mqtt-unsubscribe", "t": "some/test/topic2"}'
wget
wget -S -O- http://localhost:8812/r/corescript --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "mqtt-unsubscribe", "t": "some/test/topic2"}'
httpie
echo '{
"method": "mqtt-unsubscribe",
"t": "some/test/topic2"
}' | http POST http://localhost:8812/r/corescript Content-Type:application/json X-Auth-Key:mykey
python-requests
requests.post('http://localhost:8812/r/corescript', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'mqtt-unsubscribe', 't': 'some/test/topic2'})
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
t MQTT topic (“+” and “#” masks are allowed)
save save core script config after modification
Registry management
Safely purge registry database
Clears registry trash and invalid files. Keeps broken keys
Parameters:
API Key API key with sysfunc=yes permissions