Common methods

Common methods are present in all EVA controllers. They are used to manage controller itself.

RESTful API equivalent calls can be found in corresponding component RESTful API docs.

API basics

JSON RPC

JSON RPC 2.0 protocol is the primary EVA ICS API protocol. Note that default JSON RPC result is { “ok”: true } (instead of { “result”: “OK” } in the direct API). There’s no { result: “ERROR” } responses, 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

or

http://<ip_address:port>

(all POST requests to the root URI are processed as JSON RPC)

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 the following error codes:

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

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.

JSON RPC via HTTP GET

Embedded equipment sometimes can send HTTP GET requests only. JSON RPC API supports such calls as well.

To make JSON RPC API request with HTTP get, send it to:

http://<ip_address:port>/jrpc?i=ID&m=METHOD&p=PARAMS

where:

  • ID request ID (any custom value). If not specified, API response isn’t sent back

  • METHOD JSON RPC method to call

  • PARAMS method params, as url-encoded JSON

E.g. the following HTTP GET request will invoke method “test” with request id=1 and params { “k”: “mykey” }:

http://<ip_address:port>/jrpc?i=1&m=test&p=%7B%22k%22%3A%22mykey%22%7D

Note

JSON RPC API calls via HTTP GET are insecure, limited to 2048 bytes and can not be batch. Use JSON RPC via HTTP POST with JSON or MessagePack payload always when possible.

Direct API

Warning

Direct method calling is deprecated and scheduled to be removed (not implemented) in EVA ICS v4. Use JSON RPC API, whenever it is possible.

Common methods 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.

Direct 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"
}

Contents

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.

For SFA, the result section “connected” contains connection status of remote controllers. The API key must have an access either to “uc” and “lm” groups (“remote_uc:uc” and “remote_lm:lm”) or to particular controller oids.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 104
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "test",
    "params": {
        "k": "qwerty"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 104" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "test", "params": {"k": "qwerty"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 104" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "test", "params": {"k": "qwerty"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "test",
  "params": {
    "k": "qwerty"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:104 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '104', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'test', 'params': {'k': 'qwerty'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 1034
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "acl": {
            "allow": {
                "cmd": false,
                "device": false,
                "lock": true
            },
            "cdata": "",
            "groups": [
                "#"
            ],
            "groups_ro": [],
            "items": [],
            "items_ro": [],
            "key_id": "operator",
            "master": false,
            "pvt": [
                "#"
            ],
            "sysfunc": true
        },
        "controller": "uc/lab-ws2",
        "db_update": 1,
        "debug": true,
        "development": true,
        "layout": "enterprise",
        "log_level": 20,
        "ok": true,
        "polldelay": 0.01,
        "product_build": 2020103101,
        "product_code": "uc",
        "product_name": "EVA Universal Controller",
        "setup_mode": false,
        "system": "lab-ws2",
        "threads": 53,
        "time": 1604179751.2266004,
        "uptime": 2474,
        "version": "3.3.2"
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 103
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "save",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 103" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "save", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 103" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "save", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "save",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:103 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '103', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'save', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

Parameters:

  • k API key with sysfunc=yes permissions

check_item_access - check access to the particular item

Does not check is supervisor lock set, also does not check the item really exist

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 150
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "check_item_access",
    "params": {
        "i": "unit:tests/test1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 150" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "check_item_access", "params": {"i": "unit:tests/test1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 150" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "check_item_access", "params": {"i": "unit:tests/test1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "check_item_access",
  "params": {
    "i": "unit:tests/test1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:150 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '150', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'check_item_access', 'params': {'i': 'unit:tests/test1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 62
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
  "unit:tests/test1": {
    "r": true,
    "w": false
  }
}

Parameters:

  • k valid API key

  • i item id or list of ids

Returns:

oid list with subobjects “r”, “w” (true/false)

clear_lang_cache - Clear language cache

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 115
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "clear_lang_cache",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 115" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "clear_lang_cache", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 115" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "clear_lang_cache", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "clear_lang_cache",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:115 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '115', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'clear_lang_cache', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

cmd - execute a remote system command

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

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 178
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "cmd",
    "params": {
        "a": "0 2 3",
        "c": "test",
        "k": "mykey",
        "t": 10,
        "w": 5
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 178" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "cmd", "params": {"a": "0 2 3", "c": "test", "k": "mykey", "t": 10, "w": 5}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 178" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "cmd", "params": {"a": "0 2 3", "c": "test", "k": "mykey", "t": 10, "w": 5}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "cmd",
  "params": {
    "a": "0 2 3",
    "c": "test",
    "k": "mykey",
    "t": 10,
    "w": 5
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:178 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '178', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'cmd', 'params': {'a': '0 2 3', 'c': 'test', 'k': 'mykey', 't': 10, 'w': 5}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 579
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "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": 1604180400.947191,
            "created": 1604180395.8823428,
            "running": 1604180395.8826754
        },
        "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) or array (list)

  • w wait (in seconds) before API call sends a response. This allows to try waiting until command finish

  • t maximum time of command execution. If the command fails to finish within the specified time (in sec), it will be terminated

  • s STDIN data

install_pkg - install a package

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 188
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "install_pkg",
    "params": {
        "i": "test",
        "k": "mykey",
        "m": "<base64-encoded package>",
        "w": 5
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 188" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "install_pkg", "params": {"i": "test", "k": "mykey", "m": "<base64-encoded package>", "w": 5}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 188" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "install_pkg", "params": {"i": "test", "k": "mykey", "m": "<base64-encoded package>", "w": 5}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "install_pkg",
  "params": {
    "i": "test",
    "k": "mykey",
    "m": "<base64-encoded package>",
    "w": 5
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:188 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '188', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'install_pkg', 'params': {'i': 'test', 'k': 'mykey', 'm': '<base64-encoded package>', 'w': 5}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 428
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "call_for": "test",
        "err": null,
        "exitcode": 0,
        "finished": true,
        "function": "install_pkg",
        "out": null,
        "time": {
            "completed": 1609392604.4225385,
            "created": 1609392604.4218152,
            "running": 1609392604.4218833
        },
        "uuid": "19242b7a-999d-4eac-8c04-7375241c86a5"
    }
}

Parameters:

  • k API key with master permissions

  • i package name

  • m package content (base64-encoded tar/tgz)

  • o package setup options

  • w wait (in seconds) before API call sends a response. This allows to try waiting until the package is installed

list_plugins - get list of loaded core plugins

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 111
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_plugins",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 111" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_plugins", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 111" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_plugins", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_plugins",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:111 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '111', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_plugins', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 235
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "author": "Altertech",
            "license": "MIT",
            "name": "autotest",
            "ready": true,
            "version": "1.0.0"
        }
    ]
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 133
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set_debug",
    "params": {
        "debug": "true",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 133" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_debug", "params": {"debug": "true", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 133" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_debug", "params": {"debug": "true", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_debug",
  "params": {
    "debug": "true",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:133 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '133', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_debug', 'params': {'debug': 'true', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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.

For MQTT API calls a small shutdown delay usually should be specified to let the core send the correct API response.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 112
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "shutdown_core",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 112" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "shutdown_core", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 112" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "shutdown_core", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "shutdown_core",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:112 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '112', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'shutdown_core', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 84
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "boot_id": 307
    }
}

Returns:

current boot id. This allows client to check is the controller restarted later, by comparing returned boot id and new boot id (obtained with “test” command)

login - log in and get authentication token

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

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

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

If both token and credentials (user or API key) are specified, the function will return the token to normal mode.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 87
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "login",
    "params": {
        "p": "123",
        "u": "test"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 87" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "login", "params": {"p": "123", "u": "test"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 87" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "login", "params": {"p": "123", "u": "test"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "login",
  "params": {
    "p": "123",
    "u": "test"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:87 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '87', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'login', 'params': {'p': '123', 'u': 'test'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 165
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "key": "test",
        "token": "token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE",
        "user": "test"
    }
}

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 the authentication token

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Length: 110
Content-Type: application/json
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "logout",
    "params": {
        "k": "token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 110" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "logout", "params": {"k": "token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 110" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "logout", "params": {"k": "token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "logout",
  "params": {
    "k": "token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:110 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '110', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'logout', 'params': {'k': 'token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

Parameters:

  • k valid token

set_token_readonly - Set token read-only

Applies read-only mode for token. In read-only mode, only read-only functions work, others return result_token_restricted(15).

The method works for token-authenticated API calls only.

To exit read-only mode, user must either re-login or, to keep the current token, call “login” API method with both token and user credentials.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Length: 151
Content-Type: application/json
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set_token_readonly",
    "params": {
        "k": "token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 151" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_token_readonly", "params": {"k": "token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 151" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_token_readonly", "params": {"k": "token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_token_readonly",
  "params": {
    "k": "token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:151 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '151', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_token_readonly', 'params': {'k': 'token:pRe3FIEoLSRVD9FbTsTXhaYKm4lNwNiE'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

get_neighbor_clients - Get neighbor clients

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 146
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_neighbor_clients",
    "params": {
        "i": "main_page",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 146" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "get_neighbor_clients", "params": {"i": "main_page", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 146" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "get_neighbor_clients", "params": {"i": "main_page", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_neighbor_clients",
  "params": {
    "i": "main_page",
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:146 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '146', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'get_neighbor_clients', 'params': {'i': 'main_page', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 265
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "ki": "masterkey",
            "u": null,
            "utp": null
        },
        {
            "ki": "operator",
            "u": "operator",
            "utp": "msad"
        }
    ]
}

Parameters:

  • k valid API key

  • i neightbor client id

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 128
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_cvar",
    "params": {
        "i": "test",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 128" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "get_cvar", "params": {"i": "test", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 128" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "get_cvar", "params": {"i": "test", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_cvar",
  "params": {
    "i": "test",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:128 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '128', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'get_cvar', 'params': {'i': 'test', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 89
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 155
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set_cvar",
    "params": {
        "i": "test",
        "k": "mykey",
        "v": "some_value"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 155" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_cvar", "params": {"i": "test", "k": "mykey", "v": "some_value"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 155" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_cvar", "params": {"i": "test", "k": "mykey", "v": "some_value"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_cvar",
  "params": {
    "i": "test",
    "k": "mykey",
    "v": "some_value"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:155 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '155', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_cvar', 'params': {'i': 'test', 'k': 'mykey', 'v': 'some_value'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 131
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_lock",
    "params": {
        "k": "mykey",
        "l": "mylock1"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 131" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "get_lock", "params": {"k": "mykey", "l": "mylock1"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 131" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "get_lock", "params": {"k": "mykey", "l": "mylock1"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_lock",
  "params": {
    "k": "mykey",
    "l": "mylock1"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:131 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '131', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'get_lock', 'params': {'k': 'mykey', 'l': 'mylock1'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 132
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "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 can share locks with extrnal scripts.

Note

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

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 160
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "lock",
    "params": {
        "e": 1,
        "k": "mykey",
        "l": "mylock1",
        "t": 15
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 160" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "lock", "params": {"e": 1, "k": "mykey", "l": "mylock1", "t": 15}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 160" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "lock", "params": {"e": 1, "k": "mykey", "l": "mylock1", "t": 15}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "lock",
  "params": {
    "e": 1,
    "k": "mykey",
    "l": "mylock1",
    "t": 15
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:160 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '160', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'lock', 'params': {'e': 1, 'k': 'mykey', 'l': 'mylock1', 't': 15}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 129
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "unlock",
    "params": {
        "k": "mykey",
        "l": "mylock1"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 129" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "unlock", "params": {"k": "mykey", "l": "mylock1"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 129" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "unlock", "params": {"k": "mykey", "l": "mylock1"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "unlock",
  "params": {
    "k": "mykey",
    "l": "mylock1"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:129 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '129', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'unlock', 'params': {'k': 'mykey', 'l': 'mylock1'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 168
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "log",
    "params": {
        "k": "mykey",
        "l": "warning",
        "m": "local file system is full"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 168" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "log", "params": {"k": "mykey", "l": "warning", "m": "local file system is full"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 168" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "log", "params": {"k": "mykey", "l": "warning", "m": "local file system is full"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "log",
  "params": {
    "k": "mykey",
    "l": "warning",
    "m": "local file system is full"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:168 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '168', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'log', 'params': {'k': 'mykey', 'l': 'warning', 'm': 'local file system is full'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 143
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "log_debug",
    "params": {
        "k": "mykey",
        "m": "test debug message"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 143" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "log_debug", "params": {"k": "mykey", "m": "test debug message"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 143" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "log_debug", "params": {"k": "mykey", "m": "test debug message"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "log_debug",
  "params": {
    "k": "mykey",
    "m": "test debug message"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:143 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '143', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'log_debug', 'params': {'k': 'mykey', 'm': 'test debug message'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 141
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "log_info",
    "params": {
        "k": "mykey",
        "m": "test info message"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 141" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "log_info", "params": {"k": "mykey", "m": "test info message"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 141" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "log_info", "params": {"k": "mykey", "m": "test info message"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "log_info",
  "params": {
    "k": "mykey",
    "m": "test info message"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:141 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '141', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'log_info', 'params': {'k': 'mykey', 'm': 'test info message'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 147
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "log_warning",
    "params": {
        "k": "mykey",
        "m": "test warning message"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 147" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "log_warning", "params": {"k": "mykey", "m": "test warning message"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 147" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "log_warning", "params": {"k": "mykey", "m": "test warning message"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "log_warning",
  "params": {
    "k": "mykey",
    "m": "test warning message"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:147 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '147', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'log_warning', 'params': {'k': 'mykey', 'm': 'test warning message'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 143
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "log_error",
    "params": {
        "k": "mykey",
        "m": "test error message"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 143" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "log_error", "params": {"k": "mykey", "m": "test error message"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 143" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "log_error", "params": {"k": "mykey", "m": "test error message"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "log_error",
  "params": {
    "k": "mykey",
    "m": "test error message"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:143 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '143', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'log_error', 'params': {'k': 'mykey', 'm': 'test error message'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 149
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "log_critical",
    "params": {
        "k": "mykey",
        "m": "test critical message"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 149" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "log_critical", "params": {"k": "mykey", "m": "test critical message"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 149" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "log_critical", "params": {"k": "mykey", "m": "test critical message"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "log_critical",
  "params": {
    "k": "mykey",
    "m": "test critical message"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:149 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '149', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'log_critical', 'params': {'k': 'mykey', 'm': 'test critical message'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 165
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "log_get",
    "params": {
        "k": "mykey",
        "l": "warning",
        "n": 3,
        "t": 3600
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 165" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "log_get", "params": {"k": "mykey", "l": "warning", "n": 3, "t": 3600}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 165" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "log_get", "params": {"k": "mykey", "l": "warning", "n": 3, "t": 3600}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "log_get",
  "params": {
    "k": "mykey",
    "l": "warning",
    "n": 3,
    "t": 3600
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:165 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '165', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'log_get', 'params': {'k': 'mykey', 'l': 'warning', 'n': 3, 't': 3600}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 1034
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "dt": "2020-10-31T22:53:39.653032+01:00",
            "h": "lab-ws2",
            "l": 30,
            "lvl": "warning",
            "mod": "sysapi",
            "msg": "test warning message",
            "p": "uc",
            "t": 1604181219.6530318,
            "th": "CP Server Thread-14"
        },
        {
            "dt": "2020-10-31T22:53:39.666849+01:00",
            "h": "lab-ws2",
            "l": 40,
            "lvl": "error",
            "mod": "sysapi",
            "msg": "test error message",
            "p": "uc",
            "t": 1604181219.6668491,
            "th": "CP Server Thread-17"
        },
        {
            "dt": "2020-10-31T22:53:39.680672+01:00",
            "h": "lab-ws2",
            "l": 50,
            "lvl": "critical",
            "mod": "sysapi",
            "msg": "test critical message",
            "p": "uc",
            "t": 1604181219.6806724,
            "th": "CP Server Thread-6"
        }
    ]
}

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

  • x regex pattern filter

log_rotate - rotate log file

Deprecated, not required since 3.3.0

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 109
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "log_rotate",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 109" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "log_rotate", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 109" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "log_rotate", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "log_rotate",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:109 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '109', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'log_rotate', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 110
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "api_log_get",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 110" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "api_log_get", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 110" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "api_log_get", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "api_log_get",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:110 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '110', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'api_log_get', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 21292
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "auth": "key",
            "func": "get_lock",
            "gw": "http",
            "id": "621c849e-0a97-4233-b83a-860065cf4b50",
            "ip": "127.0.0.1",
            "ki": "masterkey",
            "params": "{\"l\":\"mylock1\"}",
            "status": "OK",
            "t": 1604180395.8382585,
            "tf": 1604180395.8424263,
            "u": null,
            "utp": null
        },
        {
            "auth": "key",
            "func": "unlock",
            "gw": "http",
            "id": "25f11256-1d08-468d-b067-3e8d2b501397",
            "ip": "127.0.0.1",
            "ki": "masterkey",
            "params": "{\"l\":\"mylock1\"}",
            "status": "OK",
            "t": 1604180395.8515046,
            "tf": 1604180395.8559692,
            "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 EVA registry config/<controller>/apikeys tree or can be created with API and stored in the user database.

Keys with the master permission can not be created.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 157
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "create_key",
    "params": {
        "i": "testkey",
        "k": "mykey",
        "save": "true"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 157" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "create_key", "params": {"i": "testkey", "k": "mykey", "save": "true"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 157" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "create_key", "params": {"i": "testkey", "k": "mykey", "save": "true"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "create_key",
  "params": {
    "i": "testkey",
    "k": "mykey",
    "save": "true"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:157 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '157', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'create_key', 'params': {'i': 'testkey', 'k': 'mykey', 'save': 'true'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 504
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "allow": [],
        "cdata": "",
        "dynamic": true,
        "groups": [],
        "groups_ro": [],
        "hosts_allow": [
            "0.0.0.0/0"
        ],
        "hosts_assign": [],
        "id": "testkey",
        "items": [],
        "items_ro": [],
        "key": "Oq9pP0OJMsBeB7YiH4PTSkZTiXxDsVgA6k4ngKifEoWR9UavxnceFgyyzIjfoIOf",
        "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 134
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "destroy_key",
    "params": {
        "i": "testkey",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 134" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "destroy_key", "params": {"i": "testkey", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 134" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "destroy_key", "params": {"i": "testkey", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "destroy_key",
  "params": {
    "i": "testkey",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:134 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '134', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'destroy_key', 'params': {'i': 'testkey', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 EVA registry can not be managed with API.

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 137
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_key_props",
    "params": {
        "i": "testkey",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 137" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_key_props", "params": {"i": "testkey", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 137" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_key_props", "params": {"i": "testkey", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_key_props",
  "params": {
    "i": "testkey",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:137 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '137', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_key_props', 'params': {'i': 'testkey', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 503
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "allow": [],
        "cdata": "",
        "dynamic": true,
        "groups": [],
        "groups_ro": [],
        "hosts_allow": [
            "0.0.0.0/0"
        ],
        "hosts_assign": [],
        "id": "testkey",
        "items": [],
        "items_ro": [],
        "key": "Oq9pP0OJMsBeB7YiH4PTSkZTiXxDsVgA6k4ngKifEoWR9UavxnceFgyyzIjfoIOf",
        "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 108
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_keys",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 108" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_keys", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 108" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_keys", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_keys",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:108 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '108', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_keys', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 1530
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "cdata": "",
            "dynamic": false,
            "key_id": "masterkey",
            "master": true
        },
        {
            "allow": {
                "cmd": true,
                "device": true,
                "lock": false
            },
            "cdata": "",
            "dynamic": true,
            "groups": [
                "#"
            ],
            "groups_ro": [],
            "items": [],
            "items_ro": [],
            "key_id": "default",
            "master": false,
            "sysfunc": false
        },
        {
            "allow": {
                "cmd": false,
                "device": false,
                "lock": true
            },
            "cdata": "",
            "dynamic": true,
            "groups": [
                "#"
            ],
            "groups_ro": [],
            "items": [],
            "items_ro": [],
            "key_id": "operator",
            "master": false,
            "pvt": [
                "#"
            ],
            "sysfunc": true
        },
        {
            "allow": {
                "cmd": false,
                "device": false,
                "lock": false
            },
            "cdata": "",
            "dynamic": true,
            "groups": [],
            "groups_ro": [],
            "items": [],
            "items_ro": [],
            "key_id": "testkey",
            "master": false,
            "sysfunc": true
        }
    ]
}

Parameters:

  • k API key with master permissions

regenerate_key - regenerate API key

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 137
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "regenerate_key",
    "params": {
        "i": "testkey",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 137" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "regenerate_key", "params": {"i": "testkey", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 137" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "regenerate_key", "params": {"i": "testkey", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "regenerate_key",
  "params": {
    "i": "testkey",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:137 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '137', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'regenerate_key', 'params': {'i': 'testkey', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 142
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "key": "GmCnj0BUfYpaGowgjSdc5iShhqq5N7m4JrTR3pT3ocF9SH5QYnDhCaSDP3eNOEXm"
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 204
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set_key_prop",
    "params": {
        "i": "testkey",
        "k": "mykey",
        "p": "sysfunc",
        "save": "true",
        "v": "true"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 204" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_key_prop", "params": {"i": "testkey", "k": "mykey", "p": "sysfunc", "save": "true", "v": "true"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 204" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_key_prop", "params": {"i": "testkey", "k": "mykey", "p": "sysfunc", "save": "true", "v": "true"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_key_prop",
  "params": {
    "i": "testkey",
    "k": "mykey",
    "p": "sysfunc",
    "save": "true",
    "v": "true"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:204 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '204', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_key_prop', 'params': {'i': 'testkey', 'k': 'mykey', 'p': 'sysfunc', 'save': 'true', 'v': 'true'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 190
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "create_user",
    "params": {
        "a": "testkey",
        "k": "mykey",
        "p": "verysecretpassword",
        "u": "test"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 190" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "create_user", "params": {"a": "testkey", "k": "mykey", "p": "verysecretpassword", "u": "test"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 190" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "create_user", "params": {"a": "testkey", "k": "mykey", "p": "verysecretpassword", "u": "test"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "create_user",
  "params": {
    "a": "testkey",
    "k": "mykey",
    "p": "verysecretpassword",
    "u": "test"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:190 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '190', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'create_user', 'params': {'a': 'testkey', 'k': 'mykey', 'p': 'verysecretpassword', 'u': 'test'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 112
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "key_id": "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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 132
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "destroy_user",
    "params": {
        "k": "mykey",
        "u": "test"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 132" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "destroy_user", "params": {"k": "mykey", "u": "test"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 132" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "destroy_user", "params": {"k": "mykey", "u": "test"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "destroy_user",
  "params": {
    "k": "mykey",
    "u": "test"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:132 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '132', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'destroy_user', 'params': {'k': 'mykey', 'u': 'test'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

Parameters:

  • k API key with master permissions

  • u user login

get_user - get user account info

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 128
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_user",
    "params": {
        "k": "mykey",
        "u": "test"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 128" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "get_user", "params": {"k": "mykey", "u": "test"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 128" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "get_user", "params": {"k": "mykey", "u": "test"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_user",
  "params": {
    "k": "mykey",
    "u": "test"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:128 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '128', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'get_user', 'params': {'k': 'mykey', 'u': 'test'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 112
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "key_id": "testkey",
        "user": "test"
    }
}

Parameters:

  • k API key with master permissions

  • u user login

list_users - list user accounts

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 109
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_users",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 109" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_users", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 109" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_users", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_users",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:109 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '109', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_users', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 140
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "key_id": "testkey",
            "user": "test"
        }
    ]
}

Parameters:

  • k API key with master permissions

set_user_key - assign API key to user

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 158
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set_user_key",
    "params": {
        "a": "masterkey",
        "k": "mykey",
        "u": "test"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 158" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_user_key", "params": {"a": "masterkey", "k": "mykey", "u": "test"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 158" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_user_key", "params": {"a": "masterkey", "k": "mykey", "u": "test"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_user_key",
  "params": {
    "a": "masterkey",
    "k": "mykey",
    "u": "test"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:158 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '158', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_user_key', 'params': {'a': 'masterkey', 'k': 'mykey', 'u': 'test'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

Parameters:

  • k API key with master permissions

  • u user login

  • a API key to assign (key id, not a key itself) or multiple keys, comma separated

set_user_password - set user password

Either master key and user login must be specified or a user must be logged in and a session token used

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 160
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "set_user_password",
    "params": {
        "k": "mykey",
        "p": "qwerty",
        "u": "test"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 160" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "set_user_password", "params": {"k": "mykey", "p": "qwerty", "u": "test"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 160" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "set_user_password", "params": {"k": "mykey", "p": "qwerty", "u": "test"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "set_user_password",
  "params": {
    "k": "mykey",
    "p": "qwerty",
    "u": "test"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:160 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '160', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'set_user_password', 'params': {'k': 'mykey', 'p': 'qwerty', 'u': 'test'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

Parameters:

  • k master key or token

  • u user login

  • p new password

list_tokens - List active session tokens

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 110
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_tokens",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 110" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_tokens", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 110" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_tokens", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_tokens",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:110 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '110', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_tokens', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 497
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "ki": "operator",
            "m": 1,
            "t": 1609942450.07001,
            "token": "token:5mdAIZcGxMobNvYLWHqncAzYRxGiEDjM",
            "u": "test",
            "utp": null
        },
        {
            "ki": "operator",
            "m": 1,
            "t": 1609942451.0943265,
            "token": "token:QmO6vhSR1xPVIVO6AdXgRokkpHrCrwUO",
            "u": "test",
            "utp": null
        }
    ]
}

Parameters:

  • k API key with master permissions

drop_tokens - Drop session token(s)

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 131
Host: localhost:8828

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "drop_tokens",
    "params": {
        "k": "mykey",
        "u": "test"
    }
}

curl

curl -i -X POST http://localhost:8828/jrpc -H "Accept: application/json" -H "Content-Length: 131" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "drop_tokens", "params": {"k": "mykey", "u": "test"}}'

wget

wget -S -O- http://localhost:8828/jrpc --header="Accept: application/json" --header="Content-Length: 131" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "drop_tokens", "params": {"k": "mykey", "u": "test"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "drop_tokens",
  "params": {
    "k": "mykey",
    "u": "test"
  }
}' | http POST http://localhost:8828/jrpc Accept:application/json Content-Length:131 Content-Type:application/json

python-requests

requests.post('http://localhost:8828/jrpc', headers={'Accept': 'application/json', 'Content-Length': '131', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'drop_tokens', 'params': {'k': 'mykey', 'u': 'test'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

Parameters:

  • k API key with master permissions

  • a session token or

  • u user name or

  • i API key id

Notifier management

disable_notifier - disable notifier

Note

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

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 137
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "disable_notifier",
    "params": {
        "i": "eva_1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 137" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "disable_notifier", "params": {"i": "eva_1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 137" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "disable_notifier", "params": {"i": "eva_1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "disable_notifier",
  "params": {
    "i": "eva_1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:137 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '137', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'disable_notifier', 'params': {'i': 'eva_1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 136
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "enable_notifier",
    "params": {
        "i": "eva_1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 136" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "enable_notifier", "params": {"i": "eva_1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 136" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "enable_notifier", "params": {"i": "eva_1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "enable_notifier",
  "params": {
    "i": "eva_1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:136 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '136', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'enable_notifier', 'params': {'i': 'eva_1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

Parameters:

  • k API key with master permissions

  • i notifier ID

get_notifier - get notifier configuration

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 133
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "get_notifier",
    "params": {
        "i": "eva_1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 133" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "get_notifier", "params": {"i": "eva_1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 133" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "get_notifier", "params": {"i": "eva_1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "get_notifier",
  "params": {
    "i": "eva_1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:133 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '133', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'get_notifier', 'params': {'i': 'eva_1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 613
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "api_enabled": true,
        "enabled": false,
        "events": [
            {
                "groups": [
                    "#"
                ],
                "subject": "state",
                "types": [
                    "#"
                ]
            },
            {
                "level": 20,
                "subject": "log"
            },
            {
                "subject": "server"
            }
        ],
        "host": "localhost",
        "id": "eva_1",
        "retain_enabled": true,
        "type": "mqtt"
    }
}

Parameters:

  • k API key with master permissions

  • i notifier ID

list_notifiers - list notifiers

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 113
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_notifiers",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 113" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_notifiers", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 113" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_notifiers", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_notifiers",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:113 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '113', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_notifiers', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 764
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": [
        {
            "api_enabled": true,
            "enabled": false,
            "events": [
                {
                    "groups": [
                        "#"
                    ],
                    "subject": "state",
                    "types": [
                        "#"
                    ]
                },
                {
                    "level": 20,
                    "subject": "log"
                },
                {
                    "subject": "server"
                }
            ],
            "frame_counter": 297,
            "host": "localhost",
            "id": "eva_1",
            "retain_enabled": true,
            "type": "mqtt"
        }
    ]
}

Parameters:

  • k API key with master permissions

restart_notifier - restart notifier

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 137
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "restart_notifier",
    "params": {
        "i": "eva_1",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 137" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "restart_notifier", "params": {"i": "eva_1", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 137" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "restart_notifier", "params": {"i": "eva_1", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "restart_notifier",
  "params": {
    "i": "eva_1",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:137 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '137', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'restart_notifier', 'params': {'i': 'eva_1', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

Parameters:

  • k API key with master permissions

  • i notifier ID

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 184
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "file_put",
    "params": {
        "i": "xc/uc/test_action_script",
        "k": "mykey",
        "m": "/bin/sh\\n\\nexit 0"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 184" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "file_put", "params": {"i": "xc/uc/test_action_script", "k": "mykey", "m": "/bin/sh\\n\\nexit 0"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 184" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "file_put", "params": {"i": "xc/uc/test_action_script", "k": "mykey", "m": "/bin/sh\\n\\nexit 0"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "file_put",
  "params": {
    "i": "xc/uc/test_action_script",
    "k": "mykey",
    "m": "/bin/sh\\n\\nexit 0"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:184 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '184', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'file_put', 'params': {'i': 'xc/uc/test_action_script', 'k': 'mykey', 'm': '/bin/sh\\n\\nexit 0'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

Parameters:

  • k API key with master permissions

  • i relative path (without first slash)

  • m file content (plain text or base64-encoded)

  • b if True - put binary file (decode base64)

file_set_exec - set file exec permission

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 174
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "file_set_exec",
    "params": {
        "e": "true",
        "i": "xc/uc/test_action_script",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 174" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "file_set_exec", "params": {"e": "true", "i": "xc/uc/test_action_script", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 174" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "file_set_exec", "params": {"e": "true", "i": "xc/uc/test_action_script", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "file_set_exec",
  "params": {
    "e": "true",
    "i": "xc/uc/test_action_script",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:174 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '174', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'file_set_exec', 'params': {'e': 'true', 'i': 'xc/uc/test_action_script', 'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 148
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "file_get",
    "params": {
        "i": "xc/uc/test_action_script",
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 148" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "file_get", "params": {"i": "xc/uc/test_action_script", "k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 148" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "file_get", "params": {"i": "xc/uc/test_action_script", "k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "file_get",
  "params": {
    "i": "xc/uc/test_action_script",
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:148 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '148', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'file_get', 'params': {'i': 'xc/uc/test_action_script', 'k': 'mykey'}})

response

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

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "content_type": "text/plain",
        "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)

  • b if True - force getting binary file (base64-encode content)

Core scripts

list_corescript_mqtt_topics - List MQTT topics core scripts react on

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 126
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "list_corescript_mqtt_topics",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 126" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "list_corescript_mqtt_topics", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 126" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "list_corescript_mqtt_topics", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "list_corescript_mqtt_topics",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:126 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '126', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'list_corescript_mqtt_topics', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 55
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": []
}

Parameters:

  • k API key with master permissions

reload_corescripts - Reload core scripts if some was added or deleted

http

POST /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 117
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "reload_corescripts",
    "params": {
        "k": "mykey"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 117" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "reload_corescripts", "params": {"k": "mykey"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 117" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "reload_corescripts", "params": {"k": "mykey"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "reload_corescripts",
  "params": {
    "k": "mykey"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:117 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '117', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'reload_corescripts', 'params': {'k': 'mykey'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 173
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "subscribe_corescripts_mqtt",
    "params": {
        "k": "mykey",
        "q": 2,
        "t": "some/test/topic"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 173" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "subscribe_corescripts_mqtt", "params": {"k": "mykey", "q": 2, "t": "some/test/topic"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 173" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "subscribe_corescripts_mqtt", "params": {"k": "mykey", "q": 2, "t": "some/test/topic"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "subscribe_corescripts_mqtt",
  "params": {
    "k": "mykey",
    "q": 2,
    "t": "some/test/topic"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:173 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '173', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'subscribe_corescripts_mqtt', 'params': {'k': 'mykey', 'q': 2, 't': 'some/test/topic'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

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 /jrpc HTTP/1.1
Accept: application/json
Content-Type: application/json
Content-Length: 159
Host: localhost:8812

{
    "id": 1,
    "jsonrpc": "2.0",
    "method": "unsubscribe_corescripts_mqtt",
    "params": {
        "k": "mykey",
        "t": "some/test/topic"
    }
}

curl

curl -i -X POST http://localhost:8812/jrpc -H "Accept: application/json" -H "Content-Length: 159" -H "Content-Type: application/json" --data-raw '{"id": 1, "jsonrpc": "2.0", "method": "unsubscribe_corescripts_mqtt", "params": {"k": "mykey", "t": "some/test/topic"}}'

wget

wget -S -O- http://localhost:8812/jrpc --header="Accept: application/json" --header="Content-Length: 159" --header="Content-Type: application/json" --post-data='{"id": 1, "jsonrpc": "2.0", "method": "unsubscribe_corescripts_mqtt", "params": {"k": "mykey", "t": "some/test/topic"}}'

httpie

echo '{
  "id": 1,
  "jsonrpc": "2.0",
  "method": "unsubscribe_corescripts_mqtt",
  "params": {
    "k": "mykey",
    "t": "some/test/topic"
  }
}' | http POST http://localhost:8812/jrpc Accept:application/json Content-Length:159 Content-Type:application/json

python-requests

requests.post('http://localhost:8812/jrpc', headers={'Accept': 'application/json', 'Content-Length': '159', 'Content-Type': 'application/json'}, json={'id': 1, 'jsonrpc': '2.0', 'method': 'unsubscribe_corescripts_mqtt', 'params': {'k': 'mykey', 't': 'some/test/topic'}})

response

HTTP/1.1 200 OK
Cache-Control: no-cache, no-store, must-revalidate
Content-Length: 79
Content-Type: application/json
Expires: 0
Pragma: no-cache

{
    "id": 1,
    "jsonrpc": "2.0",
    "result": {
        "ok": true
    }
}

Parameters:

  • k API key with master permissions

  • t MQTT topic (“+” and “#” masks are allowed)

  • save save core script config after modification

Registry management

registry_safe_purge - Safely purge registry database

Clears registry trash and invalid files. Keeps broken keys

Parameters:

  • k API key with sysfunc=yes permissions