The Settings resource is a key-value store with several use cases.

Keys have to be strings and values are interpreted as a YAML document. Settings can be manipulated via the user interface, via the REST API, and via flow scripts. Please see the Manipulating resources documentation on details how to use those methods. The examples in this document are limited to one method per use case. The method described is interchangeable with any of the other methods.

To manipulate Settings using the command line you need an authorization token. Please see the Authentication documentation on how to obtain an authorization token.


Here are some common examples of how the Settings resource can be used.

Storing Configuration Parameters

Let’s assume you use a system user to authenticate to your servers. You can store the name of the system user in a setting record:

$ curl -s '' -d '{"name":"system_user","value":"user123"}' -H "Authorization: $TOKEN"

Your flow scripts can then read the setting value whenever they want to authenticate:

def handler(system, this):
    user = system.setting('system_user').get('value')
        script='systemctl restart httpd'

If you choose to change the user name you only need to update it in one place: the setting value:

$ curl -s -X PATCH '' -d '{"value":"user789"}' -H "Authorization: $TOKEN"

and with the next execution your flow scripts will read and use the new value.

Storing Output

Your flow scripts can write the value of a setting to represent the current status of the execution:

def handler(system, this):

Other flow scripts can read the value and adapt their behaviour accordingly:

def handler(system, this):
    count = system.setting('occurrences_found').get('value')
    if count > 32:
            subject='counter alert',
            text=f'found {count} occurrences'

The value can also be retrieved using the REST API:

$ curl -s '' -H "Authorization: $TOKEN" | jq .
    "setting": {
        "client_id": "...",
        "created_at": "2020-01-09T10:59:20.862215+00:00",
        "created_by": "...",
        "id": "...",
        "lock_id": null,
        "modified_at": "2020-02-18T08:34:15.050446+00:00",
        "modified_by": "...",
        "name": "occurences_found",
        "size_bytes": 49,
        "value": 42

Settings to Add Functionality


Setting name:

client.webhook.<webhook name>

Setting content:

flow_name: my-flow-name
user_name: my-user-name
key: my-secret-api-key

This setting configures a webhook at the endpoint<webhook name>/. A GET or POST request  to that URL will execute a flow script. The webhook will return the flow with all inputs and outputs as a json response. If no response is required, adding ‘async’ as a parameter to the call will only trigger the flow and return as response only the execution id. See the webhooks documentation for more detail.

Example Calls

curl -d '{"key": "my-secret-api-key"}'
curl -d '{"key": "my-secret-api-key"}'