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
    • Standard API (direct method calling)
      • Standard API responses
    • JSON RPC
      • JSON RPC payload encoding
      • JSON RPC error responses
    • Long API calls
  • 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
    • get_cvar - get the value of user-defined variable
    • set_cvar - set the value of user-defined variable
  • Locking functions
    • get_lock - get lock status
    • lock - acquire lock
    • unlock - release lock
  • 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
    • create_key - create API key
    • destroy_key - delete API key
    • list_key_props - list API key permissions
    • list_keys - list API keys
    • regenerate_key - regenerate API key
    • set_key_prop - set API key permissions
  • User accounts
    • create_user - create user account
    • destroy_user - delete user account
    • get_user - get user account info
    • list_users - list user accounts
    • set_user_key - assign API key to user
    • set_user_password - set user password
  • Notifier management
    • disable_notifier - disable notifier
    • enable_notifier - enable notifier
    • get_notifier - get notifier configuration
    • list_notifiers - list notifiers
  • File management
    • file_put - put file to runtime folder
    • file_set_exec - set file exec permission
    • file_get - get file contents from runtime folder
    • file_unlink - delete file from runtime folder
  • Core scripts
    • list_corescript_mqtt_topics - List MQTT topics core scripts react on
    • reload_corescripts - Reload core scripts if some was added or deleted
    • subscribe_corescripts_mqtt - Subscribe core scripts to MQTT topic
    • unsubscribe_corescripts_mqtt - Unsubscribe core scripts from MQTT topic

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