SFA RESTful API

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

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

RESTful API basics

Warning

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

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

Requests

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

  • GET request is used to get information about resource or list of resources of the specified type.

  • POST request is used to perform special API calls and create resources in case when resource id is generated by server. In the last case, response always contains additional field Location which points to the resource created.

  • PUT request is used to create new resources. If resource already exists, the server could refuse recreating it, responding with 409 Conflict HTTP error.

  • PATCH request is used to modify resource parameters.

  • DELETE request is used to delete resource.

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

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

/r/<resource_type>/<group>/

Responses

Success responses:

  • 200 OK API call completed successfully

  • 201 Created API call completed successfully, Response header Location contains either uri to the newly created object or resource is accessible by the effective request uri. For resources created with PUT, body contains either serialized resource object or resource type and id

  • 202 Accepted The server accepted command and will process it later.

  • 204 No Content API call completed successfully, no content to return

Error responses:

  • 403 Forbidden the API key has no access to this function or resource

  • 404 Not Found resource doesn’t exist

  • 405 Method Not Allowed API function/method not found

  • 409 Conflict resource/object already exists or is locked

  • 500 API Error API function execution has been failed. Check input parameters and server logs.

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

Long API calls

  • Long API calls should be avoided at any cost.

  • All critical action and command methods have an option to obtain action ID and check for the result later.

  • If long API calls are performed between controllers (e.g. action methods with wait param), remote controller timeout should be always greater than max. expected “wait” timeout in API call, otherwise client controller will repeat API calls continuously, up to max retries for the target controller.

Contents

General functions

test API/key and get system info

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

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

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key any valid API key

Returns:

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

save database and runtime configuration

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

http

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

{ "method": "save" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with sysfunc=yes permissions

Clear language cache

check access to the particular item

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

Parameters:

  • API Key valid API key

  • i item id or list of ids

Returns:

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

execute a remote system command

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with allow=cmd permissions

Optionally:

  • a string of command arguments, separated by spaces (passed to the script) or array (list)

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

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

  • s STDIN data

get list of loaded core plugins

http

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

curl

curl -i -X GET http://localhost:8812/r/plugin -H "X-Auth-Key: mykey"

wget

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

httpie

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

python-requests

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

response

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

[
    {
        "author": "Altertech, https://www.altertech.com/",
        "license": "Apache License 2.0",
        "name": "test",
        "version": "0.0.1"
    }
]

Parameters:

  • API Key API key with master permissions

Returns:

list with plugin module information

install a package

Parameters:

  • API Key API key with master permissions

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

  • o package setup options

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

shutdown the controller

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

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

http

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

{ "method": "shutdown" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Returns:

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

switch debugging mode

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

http

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

{ "debug": true }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

  • debug true for enabling debug mode, false for disabling

log in and get authentication token

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

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

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

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key or

  • u user login

  • p user password

  • a authentication token

Returns:

A dict, containing API key ID and authentication token

log out and purge the authentication token

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid token

Set token read-only

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

The method works for token-authenticated API calls only.

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

Get neighbor clients

Parameters:

  • API Key valid API key

  • i neightbor client id

Item functions

clean action queue of unit

Cancels all queued actions, keeps the current action running.

http

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

{ "method": "q_clean" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

create unit control action

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key

Optionally:

  • s desired unit status

  • v desired unit value

  • w wait for the completion for the specified number of seconds

  • p queue priority (default is 100, lower is better)

  • q global queue timeout, if expires, action is marked as “dead”

Returns:

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

disable unit actions

Disables unit to run and queue new actions.

http

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

{ "action_enabled": false }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

enable unit actions

Enables unit to run and queue new actions.

http

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

{ "action_enabled": true }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

get action status or macro run result

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

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key

Optionally:

  • g filter by unit group

  • s filter by action status: Q for queued, R for running, F for finished, D for dead

Returns:

list or single serialized action object

get item group list

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

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key

get item state

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

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key

Optionally:

get item state history

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

If master key is used, the method attempts to get stored state for an item even if it doesn’t present currently in system.

The method can return state log for disconnected items as well.

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key

  • a history notifier id (default: db_1)

Optionally:

  • s start time (timestamp or ISO or e.g. 1D for -1 day)

  • e end time (timestamp or ISO or e.g. 1D for -1 day)

  • l records limit (doesn’t work with “w”)

  • x state prop (“status” or “value”)

  • t time format (“iso” or “raw” for unix timestamp, default is “raw”)

  • z Time zone (pytz, e.g. UTC or Europe/Prague)

  • w fill frame with the interval (e.g. “1T” - 1 min, “2H” - 2 hours etc.), start time is required, set to 1D if not specified

  • g output format (“list”, “dict” or “chart”, default is “list”)

  • c options for chart (dict or comma separated)

  • o extra options for notifier data request

Returns:

history data in specified format or chart image.

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

Options for chart (all are optional):

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

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

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

get item state log

State log of a single item or group of the specified type can be obtained using state_log command.

note: only SQL notifiers are supported

Difference from state_history method:

  • state_log doesn’t optimize data to be displayed on charts * the data is returned from a database as-is * a single item OID or OID mask (e.g. sensor:env/#) can be specified

note: the method supports MQTT-style masks but only masks with wildcard-ending, like “type:group/subgroup/#” are supported.

The method can return state log for disconnected items as well.

For wildcard fetching, API key should have an access to the whole chosen group.

note: record limit means the limit for records, fetched from the database, but repeating state records are automatically grouped and the actual number of returned records can be lower than requested.

http

GET /r/sensor/tests/test1@log HTTP/1.1
Host: localhost:8828
X-Auth-Key: mykey

curl

curl -i -X GET http://localhost:8828/r/sensor/tests/test1@log -H "X-Auth-Key: mykey"

wget

wget -S -O- http://localhost:8828/r/sensor/tests/test1@log --header="X-Auth-Key: mykey"

httpie

http http://localhost:8828/r/sensor/tests/test1@log X-Auth-Key:mykey

python-requests

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

response

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

[
    {
        "oid": "sensor:tests/test1",
        "status": 1,
        "t": 1607295696.9975107,
        "value": 359.0
    },
    {
        "oid": "sensor:tests/test1",
        "status": 1,
        "t": 1607295713.5487244,
        "value": 772.0
    }
]

Parameters:

  • API Key valid API key

  • a history notifier id (default: db_1)

Optionally:

  • s start time (timestamp or ISO or e.g. 1D for -1 day)

  • e end time (timestamp or ISO or e.g. 1D for -1 day)

  • l records limit (doesn’t work with “w”)

  • t time format (“iso” or “raw” for unix timestamp, default is “raw”)

  • z Time zone (pytz, e.g. UTC or Europe/Prague)

  • o extra options for notifier data request

Returns:

state log records (list)

kill unit actions

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

http

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

{ "method": "kill" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

Returns:

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

terminate action execution

Terminates or cancel the action if it is still queued

http

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

{ "method": "terminate" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

Returns:

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

toggle unit status

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key

Optionally:

  • w wait for the completion for the specified number of seconds

  • p queue priority (default is 100, lower is better)

  • q global queue timeout, if expires, action is marked as “dead”

Returns:

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

clear lvar state

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

http

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

{ "s": "clear" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

clear lvar state

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

http

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

{ "s": "toggle" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

decrement lvar value

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

http

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

{ "v": "!decrement" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

increment lvar value

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

http

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

{ "v": "!increment" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

reset lvar state

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

http

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

{ "s": "reset" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

set lvar state

Set status and value of a logic variable.

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key valid API key

Optionally:

  • s lvar status

  • v lvar value

Logic cycles

get cycle groups list

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

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

[
    "tests"
]

Parameters:

  • API Key valid API key

get cycle information

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key

Returns:

field “value” contains real average cycle interval

get cycle list

Get the list of all available cycles.

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key

Optionally:

  • i filter by controller

Logic macros

execute macro

Execute a macro with the specified arguments.

http

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

{ "method": "run" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key

Optionally:

  • a macro arguments, array or space separated

  • kw macro keyword arguments, name=value, comma separated or dict

  • w wait for the completion for the specified number of seconds

  • p queue priority (default is 100, lower is better)

  • q global queue timeout, if expires, action is marked as “dead”

get macro groups list

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

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

[
    "nogroup",
    "tests"
]

Parameters:

  • API Key valid API key

get macro list

Get the list of all available macros.

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key valid API key

Optionally:

  • i filter by controller

Supervisor functions

set supervisor API lock

When supervisor lock is set, SFA API functions become read-only for all users, except users in the lock scope.

http

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

{ "supervisor_lock": {} }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with allow=supervisor permissions

Notes:

supervisor_lock should be a dictionary. If the dictionary is empty, default lock is set.

  • attribute “l” = “<k|u>” sets lock scope (key / user)

  • attribute “c” = “<k|u>” set unlock/override scope

attribute “o” overrides lock owner (master key is required) with sub-attributes:

  • “u” = user

  • “utp” = user type (null for local, “msad” for Active Directory etc.)

  • “key_id” = API key ID

clear supervisor API lock

API key should have permission to clear existing supervisor lock

Parameters:

  • API Key API key with allow=supervisor permissions

Returns:

Successful result is returned if lock is either cleared or not set

send broadcast message

http

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

{ "m": "hello this is a test", "method": "supervisor_message" }

curl

curl -i -X POST http://localhost:8828/r/core -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"m": "hello this is a test", "method": "supervisor_message"}'

wget

wget -S -O- http://localhost:8828/r/core --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"m": "hello this is a test", "method": "supervisor_message"}'

httpie

echo '{
  "m": "hello this is a test",
  "method": "supervisor_message"
}' | http POST http://localhost:8828/r/core Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8828/r/core', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'m': 'hello this is a test', 'method': 'supervisor_message'})

response

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

Parameters:

  • API Key API key with allow=supervisor permissions

  • m message text

Notes:

If master key is used, sender can be overriden with “sender” argument, which should be a dictionary and contain:

  • u = message sender user

  • key_id = message sender API key ID

Remote controllers

connect remote controller via HTTP

Connects remote controller to the local.

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

  • u Controller API uri (proto://host:port, port not required if default)

  • a remote controller API key ($key to use local key)

Optionally:

  • m ref:MQTT notifier<mqtt_> to exchange item states in real time (default: eva_1)

  • s verify remote SSL certificate or pass invalid

  • t timeout (seconds) for the remote controller API calls

  • g controller type (“uc” or “lm”), autodetected if none

  • save save connected controller configuration on the disk immediately after creation

disable connected controller

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save configuration after successful call

disconnect controller

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

enable connected controller

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save configuration after successful call

get a list of items from connected controllers

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

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

Optionally:

  • g filter by item group

  • p filter by item type

get connected controller information

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

get controller connection parameters

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

get controllers list

Get the list of all connected controllers.

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

reload controller

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

http

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

{ "method": "reload" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

rescan controllers via UPnP

http

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

{ "method": "upnp-rescan" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

set controller connection parameters

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

Optionally:

  • save save configuration after successful call

test connection to remote controller

http

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

{ "method": "test" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

test management API connection to remote controller

http

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

{ "method": "matest" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

Connected clients

ask connected clients to reload

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

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

http

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

{ "method": "reload_clients" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

notify connected clients about server restart

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

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

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

http

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

{ "method": "notify_restart" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

CVARs

get the value of user-defined variable

Note

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

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "test": "some_value"
}

Parameters:

  • API Key API key with master permissions

Optionally:

Returns:

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

set the value of user-defined variable

http

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

{ "v": "some_value" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "test": "some_value"
}

Parameters:

  • API Key API key with master permissions

Optionally:

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

Locking functions

acquire lock

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

  • centralized for several systems (any EVA server can act as lock server)

  • removed from outside

  • automatically unlocked after the expiration time, if the initiator failed or forgot to release the lock

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

Note

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with allow=lock permissions

Optionally:

  • t maximum time (seconds) to acquire lock

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

get lock status

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with allow=lock permissions

release lock

Releases the previously acquired lock.

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with allow=lock permissions

Logging

put message to log file

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with sysfunc=yes permissions

  • l log level

  • m message text

put debug message to log file

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

Parameters:

  • API Key API key with sysfunc=yes permissions

  • m message text

put info message to log file

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

Parameters:

  • API Key API key with sysfunc=yes permissions

  • m message text

put warning message to log file

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

Parameters:

  • API Key API key with sysfunc=yes permissions

  • m message text

put error message to log file

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

Parameters:

  • API Key API key with sysfunc=yes permissions

  • m message text

put critical message to log file

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

Parameters:

  • API Key API key with sysfunc=yes permissions

  • m message text

get records from the controller log

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

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with sysfunc=yes permissions

Optionally:

  • t get log records not older than t seconds

  • n the maximum number of log records you want to obtain

  • x regex pattern filter

rotate log file

Deprecated, not required since 3.3.0

http

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

{ "method": "log_rotate" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with sysfunc=yes permissions

get API call log

  • API call with master permission returns all records requested

  • API call with other API key returns records for the specified key only

  • API call with an authentication token returns records for the current authorized user

http

GET /r/core@apilog HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X GET http://localhost:8812/r/core@apilog -H "X-Auth-Key: mykey"

wget

wget -S -O- http://localhost:8812/r/core@apilog --header="X-Auth-Key: mykey"

httpie

http http://localhost:8812/r/core@apilog X-Auth-Key:mykey

python-requests

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

response

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

[
    {
        "auth": "key",
        "func": "login",
        "gw": "http",
        "id": "a4ac6da7-2fa8-4938-8613-48e6495158b1",
        "ip": "127.0.0.1",
        "ki": "operator",
        "params": "{\"u\":\"ttt\",\"p\":\"<hidden>\"}",
        "status": "OK",
        "t": 1596055098.3651853,
        "tf": 1596055098.3837607,
        "u": "ttt",
        "utp": null
    },
    {
        "auth": "key",
        "func": "list_key_props",
        "gw": "http",
        "id": "35685960-cc2f-4fb6-8efc-c4ebca8bf9b5",
        "ip": "127.0.0.1",
        "ki": "masterkey",
        "params": "{\"i\":\"operator\"}",
        "status": "OK",
        "t": 1596055125.9569867,
        "tf": 1596055125.9690392,
        "u": null,
        "utp": null
    },
    {
        "auth": "key",
        "func": "action_toggle",
        "gw": "http",
        "id": "1bdc23da-95a1-4b41-b354-3f3c62e24405",
        "ip": "127.0.0.1",
        "ki": "masterkey",
        "params": "{\"i\":\"unit:light/hall\",\"p\":null,\"w\":null,\"q\":null,\"u\":null}",
        "status": "OK",
        "t": 1596055185.7343063,
        "tf": 1596055185.7551231,
        "u": null,
        "utp": null
    }
]

Parameters:

  • API Key any valid API key

Optionally:

  • s start time (timestamp or ISO or e.g. 1D for -1 day)

  • e end time (timestamp or ISO or e.g. 1D for -1 day)

  • n records limit

  • t time format (“iso” or “raw” for unix timestamp, default is “raw”)

  • f record filter (requires API key with master permission)

Returns:

List of API calls

Note: API call params are returned as string and can be invalid JSON data as they’re always truncated to 512 symbols in log database

Record filter should be specified either as string (k1=val1,k2=val2) or as a dict. Valid fields are:

  • gw: filter by API gateway

  • ip: filter by caller IP

  • auth: filter by authentication type

  • u: filter by user

  • utp: filter by user type

  • ki: filter by API key ID

  • func: filter by API function

  • params: filter by API call params (matches if field contains value)

  • status: filter by API call status

API keys

create API key

API keys are defined statically in EVA registry config/<controller>/apikeys tree or can be created with API and stored in the user database.

Keys with the master permission can not be created.

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

  • save save configuration immediately

Returns:

JSON with serialized key object

delete API key

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

list API key permissions

Lists API key permissons (including a key itself)

Note

API keys defined in EVA registry can not be managed with API.

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

  • save save configuration immediately

list API keys

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

regenerate API key

http

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

{ "method": "regenerate" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

{
    "key": "3dbcd3d24c6dc878cebe369eb9fdb95ae99fee14e99cdfd911b83629688d2854"
}

Parameters:

  • API Key API key with master permissions

Returns:

JSON dict with new key value in “key” field

set API key permissions

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

  • p property

  • v value (if none, permission will be revoked)

  • save save configuration immediately

User accounts

assign API key to user

http

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

{ "a": "masterkey" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

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

create user account

Note

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

  • p user password

  • a API key to assign (key id, not a key itself)

delete user account

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

get user account info

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

list user accounts

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

set user password

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

http

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

{ "p": "qwerty" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key master key or token

  • p new password

List active session tokens

Parameters:

  • API Key API key with master permissions

Drop session token(s)

Parameters:

  • API Key API key with master permissions

  • a session token or

  • u user name or

  • i API key id

Notifier management

disable notifier

Note

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

http

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

{ "enabled": false }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

enable notifier

Note

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

http

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

{ "enabled": true }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

get notifier configuration

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

list notifiers

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

restart notifier

Parameters:

  • API Key API key with master permissions

File management

put file to runtime folder

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

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

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

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

set file exec permission

http

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

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

  • e false for 0x644, true for 0x755 (executable)

delete file from runtime folder

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

get file contents from runtime folder

http

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

curl

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

wget

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

httpie

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

python-requests

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

response

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

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

Parameters:

  • API Key API key with master permissions

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

Core scripts

List MQTT topics core scripts react on

http

GET /r/corescript/mqtt-topics HTTP/1.1
Host: localhost:8812
X-Auth-Key: mykey

curl

curl -i -X GET http://localhost:8812/r/corescript/mqtt-topics -H "X-Auth-Key: mykey"

wget

wget -S -O- http://localhost:8812/r/corescript/mqtt-topics --header="X-Auth-Key: mykey"

httpie

http http://localhost:8812/r/corescript/mqtt-topics X-Auth-Key:mykey

python-requests

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

response

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

[
    {
        "qos": 2,
        "topic": "eva_1:cluster/#"
    },
    {
        "qos": 2,
        "topic": "test/test2"
    },
    {
        "qos": 1,
        "topic": "ttt/ttt"
    }
]

Parameters:

  • API Key API key with master permissions

Reload core scripts if some was added or deleted

http

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

{ "method": "reload" }

curl

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

wget

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

httpie

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

python-requests

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

response

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

Parameters:

  • API Key API key with master permissions

Subscribe core scripts to MQTT topic

The method subscribes core scripts to topic of default MQTT notifier (eva_1). To specify another notifier, set topic as <notifer_id>:<topic>

http

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

{ "q": 2, "method": "mqtt-subscribe", "t": "some/test/topic2" }

curl

curl -i -X POST http://localhost:8812/r/corescript -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "mqtt-subscribe", "q": 2, "t": "some/test/topic2"}'

wget

wget -S -O- http://localhost:8812/r/corescript --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "mqtt-subscribe", "q": 2, "t": "some/test/topic2"}'

httpie

echo '{
  "method": "mqtt-subscribe",
  "q": 2,
  "t": "some/test/topic2"
}' | http POST http://localhost:8812/r/corescript Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/corescript', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'mqtt-subscribe', 'q': 2, 't': 'some/test/topic2'})

response

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

Parameters:

  • API Key API key with master permissions

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

  • q MQTT topic QoS

  • save save core script config after modification

Unsubscribe core scripts from MQTT topic

http

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

{ "method": "mqtt-unsubscribe", "t": "some/test/topic2" }

curl

curl -i -X POST http://localhost:8812/r/corescript -H "Content-Type: application/json" -H "X-Auth-Key: mykey" --data-raw '{"method": "mqtt-unsubscribe", "t": "some/test/topic2"}'

wget

wget -S -O- http://localhost:8812/r/corescript --header="Content-Type: application/json" --header="X-Auth-Key: mykey" --post-data='{"method": "mqtt-unsubscribe", "t": "some/test/topic2"}'

httpie

echo '{
  "method": "mqtt-unsubscribe",
  "t": "some/test/topic2"
}' | http POST http://localhost:8812/r/corescript Content-Type:application/json X-Auth-Key:mykey

python-requests

requests.post('http://localhost:8812/r/corescript', headers={'Content-Type': 'application/json', 'X-Auth-Key': 'mykey'}, json={'method': 'mqtt-unsubscribe', 't': 'some/test/topic2'})

response

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

Parameters:

  • API Key API key with master permissions

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

  • save save core script config after modification

Registry management

Safely purge registry database

Clears registry trash and invalid files. Keeps broken keys

Parameters:

  • API Key API key with sysfunc=yes permissions