SYS API
SYS API is a common API present in all EVA controllers. SYS API functions are used to manage controller itself.
RESTful API equivalent calls can be found in corresponding component RESTful API docs.
API basics
Standard API (direct method calling)
SYS API functions are called through URL request
http://<ip_address:port>/sys-api/function
If SSL is allowed in the controller configuration file, you can also use https calls.
Warning
It’s highly not recommended to perform long API calls, calling API functions from JavaScript in a web browser (e.g. giving “w” param to action methods to wait until action finish). Web browser may repeat API call continuously, which may lead to absolutely unexpected behavior.
Standard API responses
Good for backward compatibility with any devices, as all API functions can be called using GET and POST. When POST is used, the parameters can be passed to functions either as multipart/form-data or as JSON.
API key can be sent in request parameters, session (if enabled and user is logged in) or in HTTP X-Auth-Key header.
Standard responses in status/body:
- 200 OK { “result”: “OK” } API call completed successfully.
Standard error responses in status:
- 400 Bad Request Invalid request params
- 403 Forbidden the API key has no access to this function or resource
- 404 Not Found method or resource/object doesn’t exist
- 405 Method Not Allowed API function/method not found or HTTP method is not either GET or POST
- 409 Conflict resource/object already exists or is locked
- 500 API Error API function execution has been failed. Check input parameters and server logs.
In case API function has been failed, response body will contain JSON data with _error field, which contains error message.
{
"_error": "unable to add object, already present",
"result": "ERROR"
}
JSON RPC
Additionally, API supports JSON RPC 2.0 protocol. Note that default JSON RPC result is { “ok”: true } (instead of { “result”: “OK” }). There’s no error result, as JSON RPC sends errors in “error” field.
If JSON RPC request is called without ID and server should not return a result, it will return http response with a code 202 Accepted.
Note
JSON RPC is recommended way to use EVA ICS API, unless direct method calling or RESTful is really required.
JSON RPC API URL:
http://<ip_address:port>/jrpc
JSON RPC payload encoding
EVA ICS supports JSON RPC payloads, encoded as generic JSON and as MessagePack. MessagePack encoding works faster, requires less bandwidth and is highly recommended to use.
To call API methods with MessagePack-encoded payloads, use Content-Type: application/msgpack HTTP request header.
JSON RPC error responses
JSON RPC calls return error codes equal to the codes of EVA API Client:
- 1 the item or resource is not found
- 2 access is denied with the set API key
- 6 Attempt to call undefined API method/function
- 10 API function failed (all errors not listed here fall within this category)
- 11 API function is called with invalid params
- 12 API function attempted to create resource which already exists and can’t be recreated until deleted/removed
- 13 the resource is busy (in use) and can not be accessed/recreated or deleted at this moment
- 14 the method is not implemented in/for requested resource
Response field “message” may contain additional information about error.
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.
Contents
- SYS API
- API basics
- General functions
- test - test API/key and get system info
- save - save database and runtime configuration
- cmd - execute a remote system command
- list_plugins - get list of loaded core plugins
- set_debug - switch debugging mode
- shutdown_core - shutdown the controller
- login - log in and get authentication token
- logout - log out and purge authentication token
- CVARs
- Locking functions
- Logging
- log - put message to log file
- log_debug - put debug message to log file
- log_info - put info message to log file
- log_warning - put warning message to log file
- log_error - put error message to log file
- log_critical - put critical message to log file
- log_get - get records from the controller log
- log_rotate - rotate log file
- api_log_get - get API call log
- API keys
- User accounts
- Notifier management
- File management
- Core scripts
General functions
test - test API/key and get system info
Test can be executed with any valid API key of the controller the function is called to.
http
POST /sys-api/test HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/test -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/test --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/test Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/test', headers={'Content-Type': 'application/json'}, json={'k': '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
{
"acl": {
"key_id": "masterkey",
"master": true
},
"db_update": 1,
"debug": true,
"file_management": true,
"layout": "enterprise",
"polldelay": 0.001,
"product_build": 2019031405,
"product_code": "uc",
"product_name": "EVA Universal Controller",
"result": "OK",
"setup_mode": false,
"system": "mws1-v1",
"time": 1552863476.453035,
"uptime": 521,
"version": "3.2.0"
}
Parameters:
- k any valid API key
Returns:
JSON dict with system info and current API key permissions (for masterkey only { “master”: true } is returned)
save - 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 /sys-api/save HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/save -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/save --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/save Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/save', headers={'Content-Type': 'application/json'}, json={'k': '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
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
cmd - execute a remote system command
Executes a command script on the server where the controller is installed.
http
POST /sys-api/cmd HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "c": "test", "a": "0 2 3", "w": 5, "t": 10 }
curl
curl -i -X POST http://localhost:8812/sys-api/cmd -H 'Content-Type: application/json' --data-raw '{"a": "0 2 3", "c": "test", "k": "mykey", "t": 10, "w": 5}'
wget
wget -S -O- http://localhost:8812/sys-api/cmd --header='Content-Type: application/json' --post-data='{"a": "0 2 3", "c": "test", "k": "mykey", "t": 10, "w": 5}'
httpie
echo '{
"a": "0 2 3",
"c": "test",
"k": "mykey",
"t": 10,
"w": 5
}' | http POST http://localhost:8812/sys-api/cmd Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/cmd', headers={'Content-Type': 'application/json'}, json={'a': '0 2 3', 'c': 'test', 'k': 'mykey', 't': 10, 'w': 5})
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
{
"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.690193,
"created": 1552863480.681957,
"running": 1552863480.682348
},
"timeout": 10.0
}
Parameters:
- k API key with allow=cmd permissions
- c name of the command script
Optionally:
- a string of command arguments, separated by spaces (passed to the script)
- w wait (in seconds) before API call sends a response. This allows to try waiting until command finish
- t maximum time of command execution. If the command fails to finish within the specified time (in sec), it will be terminated
list_plugins - get list of loaded core plugins
http
POST /sys-api/list_plugins HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/list_plugins -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/list_plugins --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/list_plugins Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/list_plugins', headers={'Content-Type': 'application/json'}, json={'k': '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
[
{
"author": "Altertech, https://www.altertech.com/",
"license": "Apache License 2.0",
"name": "test",
"version": "0.0.1"
}
]
Parameters:
- k API key with master permissions
Returns:
list with plugin module information
set_debug - 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
POST /sys-api/set_debug HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "debug": true }
curl
curl -i -X POST http://localhost:8812/sys-api/set_debug -H 'Content-Type: application/json' --data-raw '{"debug": true, "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/set_debug --header='Content-Type: application/json' --post-data='{"debug": true, "k": "mykey"}'
httpie
echo '{
"debug": true,
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/set_debug Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/set_debug', headers={'Content-Type': 'application/json'}, json={'debug': True, 'k': '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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- debug true for enabling debug mode, false for disabling
shutdown_core - shutdown the controller
Controller process will be exited and then (should be) restarted by watchdog. This allows to restart controller remotely.
http
POST /sys-api/shutdown_core HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/shutdown_core -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/shutdown_core --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/shutdown_core Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/shutdown_core', headers={'Content-Type': 'application/json'}, json={'k': 'mykey'})
response
HTTP/1.1 200 OK
Allow: GET, HEAD, PATCH, POST, PUT
Cache-Control: no-cache, no-store, must-revalidate
Content-Type: application/json
Expires: 0
Pragma: no-cache
{
"result": "OK"
}
Parameters:
- k API key with master permissions
login - log in and get authentication token
Obtains authentication token which can be used in API calls instead of API key.
If both k and u args are absent, but API method is called with HTTP request, which contain HTTP header for basic authorization, the function will try to parse it and log in user with credentials provided.
If authentication token is specified, the function will check it and return token information if it is valid.
http
POST /sys-api/login HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "u": "admin", "p": "123" }
curl
curl -i -X POST http://localhost:8812/sys-api/login -H 'Content-Type: application/json' --data-raw '{"p": "123", "u": "admin"}'
wget
wget -S -O- http://localhost:8812/sys-api/login --header='Content-Type: application/json' --post-data='{"p": "123", "u": "admin"}'
httpie
echo '{
"p": "123",
"u": "admin"
}' | http POST http://localhost:8812/sys-api/login Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/login', headers={'Content-Type': 'application/json'}, json={'p': '123', 'u': 'admin'})
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
{
"key": "masterkey",
"token": "token:1c166529bc3b06dac6e0fbaefee38ebe77c455480e11ff4431de2b10a5508899",
"user": "admin"
}
Parameters:
- k valid API key or
- u user login
- p user password
- a authentication token
Returns:
A dict, containing API key ID and authentication token
logout - log out and purge authentication token
Purges authentication token
http
POST /sys-api/logout HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7" }
curl
curl -i -X POST http://localhost:8812/sys-api/logout -H 'Content-Type: application/json' --data-raw '{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
wget
wget -S -O- http://localhost:8812/sys-api/logout --header='Content-Type: application/json' --post-data='{"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"}'
httpie
echo '{
"k": "token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7"
}' | http POST http://localhost:8812/sys-api/logout Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/logout', headers={'Content-Type': 'application/json'}, json={'k': 'token:c063c19fb54dd6b773b4f236f26ea7e5fbaa96f48b103221ae1107420096aef7'})
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
{
"result": "OK"
}
Parameters:
- k valid token
CVARs
get_cvar - 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
POST /sys-api/get_cvar HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test" }
curl
curl -i -X POST http://localhost:8812/sys-api/get_cvar -H 'Content-Type: application/json' --data-raw '{"i": "test", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/get_cvar --header='Content-Type: application/json' --post-data='{"i": "test", "k": "mykey"}'
httpie
echo '{
"i": "test",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/get_cvar Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/get_cvar', headers={'Content-Type': 'application/json'}, json={'i': 'test', 'k': '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
{
"test": "some_value"
}
Parameters:
- k API key with master permissions
Optionally:
- i variable name
Returns:
Dict containing variable and its value. If no varible name was specified, all cvars are returned.
set_cvar - set the value of user-defined variable
http
POST /sys-api/set_cvar HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "test", "v": "some_value" }
curl
curl -i -X POST http://localhost:8812/sys-api/set_cvar -H 'Content-Type: application/json' --data-raw '{"i": "test", "k": "mykey", "v": "some_value"}'
wget
wget -S -O- http://localhost:8812/sys-api/set_cvar --header='Content-Type: application/json' --post-data='{"i": "test", "k": "mykey", "v": "some_value"}'
httpie
echo '{
"i": "test",
"k": "mykey",
"v": "some_value"
}' | http POST http://localhost:8812/sys-api/set_cvar Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/set_cvar', headers={'Content-Type': 'application/json'}, json={'i': 'test', 'k': 'mykey', 'v': 'some_value'})
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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i variable name
Optionally:
- v variable value (if not specified, variable is deleted)
Locking functions
get_lock - get lock status
http
POST /sys-api/get_lock HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "l": "mylock1" }
curl
curl -i -X POST http://localhost:8812/sys-api/get_lock -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "l": "mylock1"}'
wget
wget -S -O- http://localhost:8812/sys-api/get_lock --header='Content-Type: application/json' --post-data='{"k": "mykey", "l": "mylock1"}'
httpie
echo '{
"k": "mykey",
"l": "mylock1"
}' | http POST http://localhost:8812/sys-api/get_lock Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/get_lock', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'l': 'mylock1'})
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
{
"id": "mylock1",
"locked": true,
"type": "lock"
}
Parameters:
- k API key with allow=lock permissions
- l lock id
lock - acquire lock
Locks can be used similarly to file locking by the specific process. The difference is that SYS API tokens can be:
- centralized for several systems (any EVA server can act as lock server)
- removed from outside
- automatically unlocked after the expiration time, if the initiator failed or forgot to release the lock
used to restrict parallel process starting or access to system files/resources. LM PLC macro share locks with extrnal scripts.
Note
Even if different EVA controllers are working on the same server, their lock tokens are stored in different bases. To work with the token of each subsystem, use SYS API on the respective address/port.
http
POST /sys-api/lock HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "l": "mylock1", "e": 1, "t": 15 }
curl
curl -i -X POST http://localhost:8812/sys-api/lock -H 'Content-Type: application/json' --data-raw '{"e": 1, "k": "mykey", "l": "mylock1", "t": 15}'
wget
wget -S -O- http://localhost:8812/sys-api/lock --header='Content-Type: application/json' --post-data='{"e": 1, "k": "mykey", "l": "mylock1", "t": 15}'
httpie
echo '{
"e": 1,
"k": "mykey",
"l": "mylock1",
"t": 15
}' | http POST http://localhost:8812/sys-api/lock Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/lock', headers={'Content-Type': 'application/json'}, json={'e': 1, 'k': 'mykey', 'l': 'mylock1', 't': 15})
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
{
"result": "OK"
}
Parameters:
- k API key with allow=lock permissions
- l lock id
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)
unlock - release lock
Releases the previously acquired lock.
http
POST /sys-api/unlock HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "l": "mylock1" }
curl
curl -i -X POST http://localhost:8812/sys-api/unlock -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "l": "mylock1"}'
wget
wget -S -O- http://localhost:8812/sys-api/unlock --header='Content-Type: application/json' --post-data='{"k": "mykey", "l": "mylock1"}'
httpie
echo '{
"k": "mykey",
"l": "mylock1"
}' | http POST http://localhost:8812/sys-api/unlock Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/unlock', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'l': 'mylock1'})
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
{
"result": "OK"
}
Parameters:
- k API key with allow=lock permissions
- l lock id
Logging
log - put message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "l": "warning", "m": "local file system is full" }
curl
curl -i -X POST http://localhost:8812/sys-api/log -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "l": "warning", "m": "local file system is full"}'
wget
wget -S -O- http://localhost:8812/sys-api/log --header='Content-Type: application/json' --post-data='{"k": "mykey", "l": "warning", "m": "local file system is full"}'
httpie
echo '{
"k": "mykey",
"l": "warning",
"m": "local file system is full"
}' | http POST http://localhost:8812/sys-api/log Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'l': 'warning', 'm': 'local file system is full'})
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
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- l log level
- m message text
log_debug - put debug message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log_debug HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "test debug message" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_debug -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "test debug message"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_debug --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "test debug message"}'
httpie
echo '{
"k": "mykey",
"m": "test debug message"
}' | http POST http://localhost:8812/sys-api/log_debug Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_debug', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'm': 'test debug message'})
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
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- m message text
log_info - put info message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log_info HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "test info message" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_info -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "test info message"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_info --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "test info message"}'
httpie
echo '{
"k": "mykey",
"m": "test info message"
}' | http POST http://localhost:8812/sys-api/log_info Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_info', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'm': 'test info message'})
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
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- m message text
log_warning - put warning message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log_warning HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "test warning message" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_warning -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "test warning message"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_warning --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "test warning message"}'
httpie
echo '{
"k": "mykey",
"m": "test warning message"
}' | http POST http://localhost:8812/sys-api/log_warning Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_warning', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'm': 'test warning message'})
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
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- m message text
log_error - put error message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log_error HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "test error message" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_error -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "test error message"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_error --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "test error message"}'
httpie
echo '{
"k": "mykey",
"m": "test error message"
}' | http POST http://localhost:8812/sys-api/log_error Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_error', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'm': 'test error message'})
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
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- m message text
log_critical - put critical message to log file
An external application can put a message in the logs on behalf of the controller.
http
POST /sys-api/log_critical HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "m": "test critical message" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_critical -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "m": "test critical message"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_critical --header='Content-Type: application/json' --post-data='{"k": "mykey", "m": "test critical message"}'
httpie
echo '{
"k": "mykey",
"m": "test critical message"
}' | http POST http://localhost:8812/sys-api/log_critical Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_critical', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'm': 'test critical message'})
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
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
- m message text
log_get - 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
POST /sys-api/log_get HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "l": "warning", "t": 3600, "n": 3 }
curl
curl -i -X POST http://localhost:8812/sys-api/log_get -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "l": "warning", "n": 3, "t": 3600}'
wget
wget -S -O- http://localhost:8812/sys-api/log_get --header='Content-Type: application/json' --post-data='{"k": "mykey", "l": "warning", "n": 3, "t": 3600}'
httpie
echo '{
"k": "mykey",
"l": "warning",
"n": 3,
"t": 3600
}' | http POST http://localhost:8812/sys-api/log_get Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_get', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'l': 'warning', 'n': 3, 't': 3600})
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
[
{
"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:
- k API key with sysfunc=yes permissions
Optionally:
- l log level (10 - debug, 20 - info, 30 - warning, 40 - error, 50 - critical)
- t get log records not older than t seconds
- n the maximum number of log records you want to obtain
log_rotate - rotate log file
Deprecated, not required since 3.3.0
http
POST /sys-api/log_rotate HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/log_rotate -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/log_rotate --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/log_rotate Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/log_rotate', headers={'Content-Type': 'application/json'}, json={'k': '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
{
"result": "OK"
}
Parameters:
- k API key with sysfunc=yes permissions
api_log_get - 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
POST /sys-api/api_log_get HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/api_log_get -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/api_log_get --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/api_log_get Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/api_log_get', headers={'Content-Type': 'application/json'}, json={'k': '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
[
{
"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:
- k 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_key - create API key
API keys are defined statically in etc/<controller>_apikeys.ini file as well as can be created with API and stored in user database.
Keys with master permission can not be created.
http
POST /sys-api/create_key HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "testkey", "save": true }
curl
curl -i -X POST http://localhost:8812/sys-api/create_key -H 'Content-Type: application/json' --data-raw '{"i": "testkey", "k": "mykey", "save": true}'
wget
wget -S -O- http://localhost:8812/sys-api/create_key --header='Content-Type: application/json' --post-data='{"i": "testkey", "k": "mykey", "save": true}'
httpie
echo '{
"i": "testkey",
"k": "mykey",
"save": true
}' | http POST http://localhost:8812/sys-api/create_key Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/create_key', headers={'Content-Type': 'application/json'}, json={'i': 'testkey', 'k': 'mykey', 'save': True})
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
{
"allow": [],
"dynamic": true,
"groups": [],
"hosts_allow": [
"0.0.0.0/0"
],
"hosts_assign": [],
"id": "testkey",
"items": [],
"key": "c143d2e3a484e165a8d243395702bef6821b933ca7bc93ee5011ad02cb6ea36d",
"master": false,
"pvt": [],
"rpvt": [],
"sysfunc": false
}
Parameters:
- k API key with master permissions
- i API key ID
- save save configuration immediately
Returns:
JSON with serialized key object
destroy_key - delete API key
http
POST /sys-api/destroy_key HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "testkey" }
curl
curl -i -X POST http://localhost:8812/sys-api/destroy_key -H 'Content-Type: application/json' --data-raw '{"i": "testkey", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/destroy_key --header='Content-Type: application/json' --post-data='{"i": "testkey", "k": "mykey"}'
httpie
echo '{
"i": "testkey",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/destroy_key Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/destroy_key', headers={'Content-Type': 'application/json'}, json={'i': 'testkey', 'k': '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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i API key ID
list_key_props - list API key permissions
Lists API key permissons (including a key itself)
Note
API keys, defined in etc/<controller>_apikeys.ini file can not be managed with API.
http
POST /sys-api/list_key_props HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "testkey" }
curl
curl -i -X POST http://localhost:8812/sys-api/list_key_props -H 'Content-Type: application/json' --data-raw '{"i": "testkey", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/list_key_props --header='Content-Type: application/json' --post-data='{"i": "testkey", "k": "mykey"}'
httpie
echo '{
"i": "testkey",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/list_key_props Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/list_key_props', headers={'Content-Type': 'application/json'}, json={'i': 'testkey', 'k': '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
{
"allow": [],
"dynamic": true,
"groups": [],
"hosts_allow": [
"0.0.0.0/0"
],
"hosts_assign": [],
"id": "testkey",
"items": [],
"key": "c143d2e3a484e165a8d243395702bef6821b933ca7bc93ee5011ad02cb6ea36d",
"master": false,
"pvt": [],
"rpvt": [],
"sysfunc": true
}
Parameters:
- k API key with master permissions
- i API key ID
- save save configuration immediately
list_keys - list API keys
http
POST /sys-api/list_keys HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/list_keys -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/list_keys --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/list_keys Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/list_keys', headers={'Content-Type': 'application/json'}, json={'k': '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
[
{
"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:
- k API key with master permissions
regenerate_key - regenerate API key
http
POST /sys-api/regenerate_key HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "testkey" }
curl
curl -i -X POST http://localhost:8812/sys-api/regenerate_key -H 'Content-Type: application/json' --data-raw '{"i": "testkey", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/regenerate_key --header='Content-Type: application/json' --post-data='{"i": "testkey", "k": "mykey"}'
httpie
echo '{
"i": "testkey",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/regenerate_key Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/regenerate_key', headers={'Content-Type': 'application/json'}, json={'i': 'testkey', 'k': '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
{
"key": "28baa61356c0b583c8286063fa7836c2c16fc3c2dc45325d00bd2363f3ef128b"
}
Parameters:
- k API key with master permissions
- i API key ID
Returns:
JSON dict with new key value in “key” field
set_key_prop - set API key permissions
http
POST /sys-api/set_key_prop HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "testkey", "save": true, "p": "sysfunc", "v": true }
curl
curl -i -X POST http://localhost:8812/sys-api/set_key_prop -H 'Content-Type: application/json' --data-raw '{"i": "testkey", "k": "mykey", "p": "sysfunc", "save": true, "v": true}'
wget
wget -S -O- http://localhost:8812/sys-api/set_key_prop --header='Content-Type: application/json' --post-data='{"i": "testkey", "k": "mykey", "p": "sysfunc", "save": true, "v": true}'
httpie
echo '{
"i": "testkey",
"k": "mykey",
"p": "sysfunc",
"save": true,
"v": true
}' | http POST http://localhost:8812/sys-api/set_key_prop Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/set_key_prop', headers={'Content-Type': 'application/json'}, json={'i': 'testkey', 'k': 'mykey', 'p': 'sysfunc', 'save': True, 'v': True})
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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i API key ID
- p property
- v value (if none, permission will be revoked)
- save save configuration immediately
User accounts
create_user - 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
POST /sys-api/create_user HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "u": "test", "p": "verysecretpassword", "a": "testkey" }
curl
curl -i -X POST http://localhost:8812/sys-api/create_user -H 'Content-Type: application/json' --data-raw '{"a": "testkey", "k": "mykey", "p": "verysecretpassword", "u": "test"}'
wget
wget -S -O- http://localhost:8812/sys-api/create_user --header='Content-Type: application/json' --post-data='{"a": "testkey", "k": "mykey", "p": "verysecretpassword", "u": "test"}'
httpie
echo '{
"a": "testkey",
"k": "mykey",
"p": "verysecretpassword",
"u": "test"
}' | http POST http://localhost:8812/sys-api/create_user Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/create_user', headers={'Content-Type': 'application/json'}, json={'a': 'testkey', 'k': 'mykey', 'p': 'verysecretpassword', 'u': 'test'})
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
{
"key": "testkey",
"user": "test"
}
Parameters:
- k API key with master permissions
- u user login
- p user password
- a API key to assign (key id, not a key itself)
destroy_user - delete user account
http
POST /sys-api/destroy_user HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "u": "test" }
curl
curl -i -X POST http://localhost:8812/sys-api/destroy_user -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "u": "test"}'
wget
wget -S -O- http://localhost:8812/sys-api/destroy_user --header='Content-Type: application/json' --post-data='{"k": "mykey", "u": "test"}'
httpie
echo '{
"k": "mykey",
"u": "test"
}' | http POST http://localhost:8812/sys-api/destroy_user Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/destroy_user', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'u': 'test'})
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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- u user login
get_user - get user account info
http
POST /sys-api/get_user HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "u": "test" }
curl
curl -i -X POST http://localhost:8812/sys-api/get_user -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "u": "test"}'
wget
wget -S -O- http://localhost:8812/sys-api/get_user --header='Content-Type: application/json' --post-data='{"k": "mykey", "u": "test"}'
httpie
echo '{
"k": "mykey",
"u": "test"
}' | http POST http://localhost:8812/sys-api/get_user Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/get_user', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'u': 'test'})
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
{
"key": "testkey",
"user": "test"
}
Parameters:
- k API key with master permissions
- u user login
list_users - list user accounts
http
POST /sys-api/list_users HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/list_users -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/list_users --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/list_users Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/list_users', headers={'Content-Type': 'application/json'}, json={'k': '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
[
{
"key_id": "test",
"user": "divisor"
},
{
"key_id": "testkey",
"user": "test"
},
{
"key_id": "testkey",
"user": "test2"
}
]
Parameters:
- k API key with master permissions
set_user_key - assign API key to user
http
POST /sys-api/set_user_key HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "u": "test", "a": "masterkey" }
curl
curl -i -X POST http://localhost:8812/sys-api/set_user_key -H 'Content-Type: application/json' --data-raw '{"a": "masterkey", "k": "mykey", "u": "test"}'
wget
wget -S -O- http://localhost:8812/sys-api/set_user_key --header='Content-Type: application/json' --post-data='{"a": "masterkey", "k": "mykey", "u": "test"}'
httpie
echo '{
"a": "masterkey",
"k": "mykey",
"u": "test"
}' | http POST http://localhost:8812/sys-api/set_user_key Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/set_user_key', headers={'Content-Type': 'application/json'}, json={'a': 'masterkey', 'k': 'mykey', 'u': 'test'})
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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- u user login
- a API key to assign (key id, not a key itself)
set_user_password - set user password
http
POST /sys-api/set_user_password HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "u": "test", "p": "qwerty" }
curl
curl -i -X POST http://localhost:8812/sys-api/set_user_password -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "p": "qwerty", "u": "test"}'
wget
wget -S -O- http://localhost:8812/sys-api/set_user_password --header='Content-Type: application/json' --post-data='{"k": "mykey", "p": "qwerty", "u": "test"}'
httpie
echo '{
"k": "mykey",
"p": "qwerty",
"u": "test"
}' | http POST http://localhost:8812/sys-api/set_user_password Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/set_user_password', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'p': 'qwerty', 'u': 'test'})
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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- u user login
- p new password
Notifier management
disable_notifier - disable notifier
Note
The notifier is disabled until controller restart. To disable notifier permanently, use notifier management CLI.
http
POST /sys-api/disable_notifier HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "eva_1" }
curl
curl -i -X POST http://localhost:8812/sys-api/disable_notifier -H 'Content-Type: application/json' --data-raw '{"i": "eva_1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/disable_notifier --header='Content-Type: application/json' --post-data='{"i": "eva_1", "k": "mykey"}'
httpie
echo '{
"i": "eva_1",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/disable_notifier Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/disable_notifier', headers={'Content-Type': 'application/json'}, json={'i': 'eva_1', 'k': '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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i notifier ID
enable_notifier - enable notifier
Note
The notifier is enabled until controller restart. To enable notifier permanently, use notifier management CLI.
http
POST /sys-api/enable_notifier HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "eva_1" }
curl
curl -i -X POST http://localhost:8812/sys-api/enable_notifier -H 'Content-Type: application/json' --data-raw '{"i": "eva_1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/enable_notifier --header='Content-Type: application/json' --post-data='{"i": "eva_1", "k": "mykey"}'
httpie
echo '{
"i": "eva_1",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/enable_notifier Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/enable_notifier', headers={'Content-Type': 'application/json'}, json={'i': 'eva_1', 'k': '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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i notifier ID
get_notifier - get notifier configuration
http
POST /sys-api/get_notifier HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "eva_1" }
curl
curl -i -X POST http://localhost:8812/sys-api/get_notifier -H 'Content-Type: application/json' --data-raw '{"i": "eva_1", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/get_notifier --header='Content-Type: application/json' --post-data='{"i": "eva_1", "k": "mykey"}'
httpie
echo '{
"i": "eva_1",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/get_notifier Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/get_notifier', headers={'Content-Type': 'application/json'}, json={'i': 'eva_1', 'k': '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
{
"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:
- k API key with master permissions
- i notifier ID
list_notifiers - list notifiers
http
POST /sys-api/list_notifiers HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/list_notifiers -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/list_notifiers --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/list_notifiers Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/list_notifiers', headers={'Content-Type': 'application/json'}, json={'k': '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
[
{
"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:
- k API key with master permissions
File management
file_put - 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
POST /sys-api/file_put HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "xc/uc/test_action_script", "m": "/bin/sh\n\nexit 0" }
curl
curl -i -X POST http://localhost:8812/sys-api/file_put -H 'Content-Type: application/json' --data-raw '{"i": "xc/uc/test_action_script", "k": "mykey", "m": "/bin/sh\n\nexit 0"}'
wget
wget -S -O- http://localhost:8812/sys-api/file_put --header='Content-Type: application/json' --post-data='{"i": "xc/uc/test_action_script", "k": "mykey", "m": "/bin/sh\n\nexit 0"}'
httpie
echo '{
"i": "xc/uc/test_action_script",
"k": "mykey",
"m": "/bin/sh\n\nexit 0"
}' | http POST http://localhost:8812/sys-api/file_put Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/file_put', headers={'Content-Type': 'application/json'}, json={'i': 'xc/uc/test_action_script', 'k': 'mykey', 'm': '/bin/sh\n\nexit 0'})
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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i relative path (without first slash)
- m file content
file_set_exec - set file exec permission
http
POST /sys-api/file_set_exec HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "xc/uc/test_action_script", "e": true }
curl
curl -i -X POST http://localhost:8812/sys-api/file_set_exec -H 'Content-Type: application/json' --data-raw '{"e": true, "i": "xc/uc/test_action_script", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/file_set_exec --header='Content-Type: application/json' --post-data='{"e": true, "i": "xc/uc/test_action_script", "k": "mykey"}'
httpie
echo '{
"e": true,
"i": "xc/uc/test_action_script",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/file_set_exec Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/file_set_exec', headers={'Content-Type': 'application/json'}, json={'e': True, 'i': 'xc/uc/test_action_script', 'k': '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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i relative path (without first slash)
- e false for 0x644, true for 0x755 (executable)
file_get - get file contents from runtime folder
http
POST /sys-api/file_get HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "xc/uc/test_action_script" }
curl
curl -i -X POST http://localhost:8812/sys-api/file_get -H 'Content-Type: application/json' --data-raw '{"i": "xc/uc/test_action_script", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/file_get --header='Content-Type: application/json' --post-data='{"i": "xc/uc/test_action_script", "k": "mykey"}'
httpie
echo '{
"i": "xc/uc/test_action_script",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/file_get Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/file_get', headers={'Content-Type': 'application/json'}, json={'i': 'xc/uc/test_action_script', 'k': '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
{
"data": "/bin/sh\n\nexit 0",
"e": false,
"file": "xc/uc/test_action_script"
}
Parameters:
- k API key with master permissions
- i relative path (without first slash)
file_unlink - delete file from runtime folder
http
POST /sys-api/file_unlink HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "i": "xc/uc/test_action_script" }
curl
curl -i -X POST http://localhost:8812/sys-api/file_unlink -H 'Content-Type: application/json' --data-raw '{"i": "xc/uc/test_action_script", "k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/file_unlink --header='Content-Type: application/json' --post-data='{"i": "xc/uc/test_action_script", "k": "mykey"}'
httpie
echo '{
"i": "xc/uc/test_action_script",
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/file_unlink Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/file_unlink', headers={'Content-Type': 'application/json'}, json={'i': 'xc/uc/test_action_script', 'k': '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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- i relative path (without first slash)
Core scripts
list_corescript_mqtt_topics - List MQTT topics core scripts react on
http
POST /sys-api/list_corescript_mqtt_topics HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/list_corescript_mqtt_topics -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/list_corescript_mqtt_topics --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/list_corescript_mqtt_topics Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/list_corescript_mqtt_topics', headers={'Content-Type': 'application/json'}, json={'k': '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
[
{
"qos": 2,
"topic": "eva_1:cluster/#"
},
{
"qos": 2,
"topic": "test/test2"
},
{
"qos": 1,
"topic": "ttt/ttt"
}
]
Parameters:
- k API key with master permissions
reload_corescripts - Reload core scripts if some was added or deleted
http
POST /sys-api/reload_corescripts HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey" }
curl
curl -i -X POST http://localhost:8812/sys-api/reload_corescripts -H 'Content-Type: application/json' --data-raw '{"k": "mykey"}'
wget
wget -S -O- http://localhost:8812/sys-api/reload_corescripts --header='Content-Type: application/json' --post-data='{"k": "mykey"}'
httpie
echo '{
"k": "mykey"
}' | http POST http://localhost:8812/sys-api/reload_corescripts Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/reload_corescripts', headers={'Content-Type': 'application/json'}, json={'k': '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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
subscribe_corescripts_mqtt - 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 /sys-api/subscribe_corescripts_mqtt HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "t": "some/test/topic", "q": 2 }
curl
curl -i -X POST http://localhost:8812/sys-api/subscribe_corescripts_mqtt -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "q": 2, "t": "some/test/topic"}'
wget
wget -S -O- http://localhost:8812/sys-api/subscribe_corescripts_mqtt --header='Content-Type: application/json' --post-data='{"k": "mykey", "q": 2, "t": "some/test/topic"}'
httpie
echo '{
"k": "mykey",
"q": 2,
"t": "some/test/topic"
}' | http POST http://localhost:8812/sys-api/subscribe_corescripts_mqtt Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/subscribe_corescripts_mqtt', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 'q': 2, 't': 'some/test/topic'})
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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- t MQTT topic (“+” and “#” masks are supported)
- q MQTT topic QoS
- save save core script config after modification
unsubscribe_corescripts_mqtt - Unsubscribe core scripts from MQTT topic
http
POST /sys-api/unsubscribe_corescripts_mqtt HTTP/1.1
Host: localhost:8812
Content-Type: application/json
{ "k": "mykey", "t": "some/test/topic" }
curl
curl -i -X POST http://localhost:8812/sys-api/unsubscribe_corescripts_mqtt -H 'Content-Type: application/json' --data-raw '{"k": "mykey", "t": "some/test/topic"}'
wget
wget -S -O- http://localhost:8812/sys-api/unsubscribe_corescripts_mqtt --header='Content-Type: application/json' --post-data='{"k": "mykey", "t": "some/test/topic"}'
httpie
echo '{
"k": "mykey",
"t": "some/test/topic"
}' | http POST http://localhost:8812/sys-api/unsubscribe_corescripts_mqtt Content-Type:application/json
python-requests
requests.post('http://localhost:8812/sys-api/unsubscribe_corescripts_mqtt', headers={'Content-Type': 'application/json'}, json={'k': 'mykey', 't': 'some/test/topic'})
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
{
"result": "OK"
}
Parameters:
- k API key with master permissions
- t MQTT topic (“+” and “#” masks are allowed)
- save save core script config after modification