diff --git a/doc/11-cli-commands.md b/doc/11-cli-commands.md
index 5b58c4c52..46c6e718c 100644
--- a/doc/11-cli-commands.md
+++ b/doc/11-cli-commands.md
@@ -22,7 +22,7 @@ Supported commands:
   * api setup (setup for API)
   * ca list (lists all certificate signing requests)
   * ca sign (signs an outstanding certificate request)
-  * console (Icinga console)
+  * console (Icinga debug console)
   * daemon (starts Icinga 2)
   * feature disable (disables specified feature)
   * feature enable (enables specified feature)
@@ -272,7 +272,7 @@ are required for executing config expressions and auto-completion.
 
 > **Note**
 >
-> The debug console does not currently support SSL certificate verification.
+> The debug console does not currently support TLS certificate verification.
 >
 > Runtime modifications are not validated and might cause the Icinga 2
 > daemon to crash or behave in an unexpected way. Use these runtime changes
diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md
index bfeca45fb..0984fb6be 100644
--- a/doc/12-icinga2-api.md
+++ b/doc/12-icinga2-api.md
@@ -14,12 +14,12 @@ certificates as well as a new API user `root` with an auto-generated password in
 Make sure to restart Icinga 2 to enable the changes you just made:
 
 ```
-# service icinga2 restart
+# systemctl restart icinga2
 ```
 
 If you prefer to set up the API manually, you will have to perform the following steps:
 
-* Set up X.509 certificates for Icinga 2
+* Set up X.509 TLS certificates for Icinga 2
 * Enable the `api` feature (`icinga2 feature enable api`)
 * Create an `ApiUser` object for authentication
 
@@ -62,7 +62,7 @@ Supported request methods:
   PUT    | Create a new object. The PUT request must include all attributes required to create a new object.
   DELETE | Remove an object created by the API. The DELETE method is idempotent and does not require any check if the object actually exists.
 
-All requests apart from `GET` require that the following `Accept` header is set:
+All requests except `GET` require the following `Accept` header:
 
 ```
 Accept: application/json
@@ -70,7 +70,7 @@ Accept: application/json
 
 Each URL is prefixed with the API version (currently "/v1").
 
-HTTP header size is limited to 8KB.
+HTTP header size is limited to 8KB per request.
 
 ### Responses <a id="icinga2-api-responses"></a>
 
@@ -93,15 +93,25 @@ The output will be sent back as a JSON object:
 
 > **Tip**
 >
-> You can use the [pretty](12-icinga2-api.md#icinga2-api-parameters-global) parameter to beautify the JSON response with Icinga v2.9+.
+> You can use the [pretty](12-icinga2-api.md#icinga2-api-parameters-global) parameter to beautify the JSON response.
 
 You can also use [jq](https://stedolan.github.io/jq/) or `python -m json.tool`
 in combination with curl on the CLI.
 
 ```
+curl ... | jq 
 curl ... | python -m json.tool
 ```
 
+jq also has additional filter capabilities, as shown in [this blogpost](https://www.netways.de/blog/2018/08/24/json-in-bequem/).
+
+```
+curl ... |jq '{name: .results[].name}'
+```
+
+For programmatic examples in various languages, check the chapter
+[below](12-icinga2-api.md#icinga2-api-clients).
+
 > **Note**
 >
 > Future versions of Icinga 2 might set additional fields. Your application
@@ -132,8 +142,8 @@ and Icinga 2 is unable to process your request.
 
 There are two different ways for authenticating against the Icinga 2 API:
 
-* username and password using HTTP basic auth
-* X.509 certificate
+* Username and password using HTTP basic auth
+* X.509 client certificate
 
 In order to configure a new API user you'll need to add a new [ApiUser](09-object-types.md#objecttype-apiuser)
 configuration object. In this example `root` will be the basic auth username
@@ -161,6 +171,8 @@ object ApiUser "root" {
 
 An `ApiUser` object can have both authentication methods configured.
 
+#### Authentication Test <a id="icinga2-api-authentication-test"></a>
+
 You can test authentication by sending a GET request to the API:
 
 ```
@@ -236,6 +248,12 @@ permissions = [
 
 More information about filters can be found in the [filters](12-icinga2-api.md#icinga2-api-filters) chapter.
 
+Prior to setting complex permissions, ensure to always [test](12-icinga2-api.md#icinga2-api-authentication-test)
+them step by step.
+
+
+#### Overview <a id="icinga2-api-permissions-overview"></a>
+
 Permissions are tied to a maximum HTTP request size to prevent abuse, responses sent by Icinga are not limited.
 An API user with all permissions ("\*") may send up to 512 MB regardless of the endpoint.
 
@@ -259,6 +277,7 @@ Available permissions for specific URL endpoints:
 
 The required actions or types can be replaced by using a wildcard match ("\*").
 
+
 ### Parameters <a id="icinga2-api-parameters"></a>
 
 Depending on the request method there are two ways of passing parameters to the request:
@@ -284,6 +303,10 @@ Here are the exact same query parameters as a JSON object:
 The [match function](18-library-reference.md#global-functions-match) is available as global function
 in Icinga 2.
 
+Whenever filters and other URL parameters don't work due to encoding issues,
+consider passing them in the request body. For GET requests, this method is explained
+[here](12-icinga2-api.md#icinga2-api-requests-method-override).
+
 ### Global Parameters <a id="icinga2-api-parameters-global"></a>
 
 Name            | Description
@@ -303,8 +326,6 @@ Example as JSON object:
 { "pretty": true }
 ```
 
-Both parameters have been added in Icinga 2 v2.9.
-
 ### Request Method Override <a id="icinga2-api-requests-method-override"></a>
 
 `GET` requests do not allow you to send a request body. In case you cannot pass everything as URL
@@ -314,13 +335,27 @@ header. This comes in handy when you are using HTTP proxies disallowing `PUT` or
 Query an existing object by sending a `POST` request with `X-HTTP-Method-Override: GET` as request header:
 
 ```
-$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -X POST -H 'X-HTTP-Method-Override: GET' 'https://localhost:5665/v1/objects/hosts'
+$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' \
+ -H 'X-HTTP-Method-Override: GET' -X POST \
+ 'https://localhost:5665/v1/objects/hosts'
 ```
 
 Delete an existing object by sending a `POST` request with `X-HTTP-Method-Override: DELETE` as request header:
 
 ```
-$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -X POST -H 'X-HTTP-Method-Override: DELETE' 'https://localhost:5665/v1/objects/hosts/example.localdomain'
+$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' \
+ -H 'X-HTTP-Method-Override: DELETE' -X POST \
+ 'https://localhost:5665/v1/objects/hosts/example.localdomain'
+```
+
+Query objects with complex filters. For a detailed introduction into filter, please
+read the [following chapter](12-icinga2-api.md#icinga2-api-filters).
+
+```
+curl -k -s -u 'root:icinga' -H 'Accept: application/json' \
+ -H 'X-HTTP-Method-Override: GET' -X POST \
+ 'https://localhost:5665/v1/objects/services' \
+ -d '{ "filter": "service.state==2 && match(\"ping*\",service.name)" }'
 ```
 
 ### Filters <a id="icinga2-api-filters"></a>
@@ -366,7 +401,11 @@ The full name of an object can be obtained by looking at the `__name` attribute.
 Most of the information provided in this chapter applies to both permission filters (as used when
 configuring `ApiUser` objects) and filters specified in queries.
 
-Advanced filters allow users to filter objects using lambda expressions. The syntax for these filters is the same like for [apply rule expressions](03-monitoring-basics.md#using-apply-expressions).
+Advanced filters allow users to filter objects using lambda expressions.
+The syntax for these filters is the same like for [apply rule expressions](03-monitoring-basics.md#using-apply-expressions).
+
+The `filter` parameter can only be specified once, complex filters must
+be defined once in the provided string value.
 
 > **Note**
 >
@@ -390,6 +429,11 @@ Example for all hosts which are in the host group `linux-servers`:
 https://localhost:5665/v1/objects/hosts?filter="linux-servers" in host.groups
 ```
 
+> **Tip**
+>
+> Best practice for filters is to use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
+> for GET requests and always pass them in the request body.
+
 User-specified filters are run in a sandbox environment which ensures that filters cannot
 modify Icinga's state, for example object attributes or global variables.
 
@@ -411,21 +455,40 @@ action which can be used for both hosts and services. When using advanced filter
 type using the `type` parameter:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/reschedule-check' \
--d '{ "type": "Service", "filter": "service.name==\"ping6\"", "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
+ 'https://localhost:5665/v1/actions/reschedule-check' \
+ -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "pretty": true }'
 ```
 
-When building filters you have to ensure that values such as
-`"linux-servers"` are escaped properly according to the rules of the Icinga 2 configuration
-language.
+##### Filter Variables <a id="icinga2-api-advanced-filters-variables"></a>
 
-To make using the API in scripts easier you can use the `filter_vars` attribute to specify
-variables which should be made available to your filter expression. This way you don't have
-to worry about escaping values:
+Filter values need to be escaped in the same way as in the Icinga 2 DSL.
+
+The example below is not valid:
 
 ```
-$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/hosts' \
--d '{ "filter": "host.vars.os == os", "filter_vars": { "os": "Linux" }, "pretty": true }'
+-d '{ "type": "Host", "filter": ""linux-servers" in host.groups" }'
+```
+
+The double quotes need to be escaped with a preceeding backslash:
+
+```
+-d '{ "type": "Host", "filter": "\"linux-servers\" in host.groups" }'
+```
+
+You can use the `filter_vars` attribute to avoid additional escaping.
+This follows the same principle as with parameter binding known from RDBMS.
+Specify a placeholder variable inside the `filter` string, and actually
+assign its value inside the `filter_vars` dictionary.
+
+That way you can also keep the `filter` string the same for different
+requests with only changing the `filter_vars`.
+
+```
+$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' \
+ -H 'X-HTTP-Method-Override: GET' -X POST \
+ 'https://localhost:5665/v1/objects/hosts' \
+ -d '{ "filter": "group in host.groups", "filter_vars": { "group": "linux-servers" }, "pretty": true }'
 ```
 
 We're using [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override) here because
@@ -434,6 +497,16 @@ the HTTP specification does not allow message bodies for GET requests.
 The `filters_vars` attribute can only be used inside the request body, but not as
 a URL parameter because there is no way to specify a dictionary in a URL.
 
+The example from [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
+can be enhanced to avoid additional parameter value escaping.
+
+```
+curl -k -s -u 'root:icinga' -H 'Accept: application/json' \
+ -H 'X-HTTP-Method-Override: GET' -X POST \
+ 'https://localhost:5665/v1/objects/services' \
+ -d '{ "filter": "service.state==state && match(pattern,service.name)", "filter_vars": { "state": 2, "pattern": "ping*" } }'
+```
+
 ## Config Objects <a id="icinga2-api-config-objects"></a>
 
 Provides methods to manage configuration objects:
@@ -611,6 +684,18 @@ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/objects/services?attrs=di
 }
 ```
 
+> **Tip**
+>
+> Use [X-HTTP-Method-Override](12-icinga2-api.md#icinga2-api-requests-method-override)
+> and pass everything in the request body like this:
+
+```
+$ curl -k -s -u 'root:icinga' -H 'Accept: application/json' \
+ -H 'X-HTTP-Method-Override: GET' -X POST \
+ 'https://localhost:5665/v1/objects/services' \
+ -d '{ "attrs": [ "display_name", "check_command" ], "joins": [ "host.name", "host.address" ], "filter": "host.vars.os==\"Linux\"", "pretty": true }'
+```
+
 In case you want to fetch all [comments](09-object-types.md#objecttype-comment)
 for hosts and services, you can use the following query URL (similar example
 for downtimes):
@@ -624,7 +709,9 @@ and no downtime or acknowledgement set). We're using [X-HTTP-Method-Override](12
 here because we want to pass all query attributes in the request body.
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://127.0.0.1:5665/v1/objects/services' \
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -H 'X-HTTP-Method-Override: GET' -X POST \
+ 'https://127.0.0.1:5665/v1/objects/services' \
 -d '{ "joins": [ "host.name", "host.address" ], "attrs": [ "name", "state", "downtime_depth", "acknowledgement" ], "filter": "service.state != ServiceOK && service.downtime_depth == 0.0 && service.acknowledgement == 0.0", "pretty": true }'
 
 {
@@ -655,8 +742,10 @@ URL endpoint with `joins` and `filter` request parameters using the [X-HTTP-Meth
 method:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5665/v1/objects/comments' \
--d '{ "joins": [ "service.name", "service.acknowledgement", "service.acknowledgement_expiry" ], "attrs": [ "author", "text" ], "filter": "service.acknowledgement!=0 && service.acknowledgement_expiry==0", "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -H 'X-HTTP-Method-Override: GET' -X POST \
+ 'https://localhost:5665/v1/objects/comments' \
+ -d '{ "joins": [ "service.name", "service.acknowledgement", "service.acknowledgement_expiry" ], "attrs": [ "author", "text" ], "filter": "service.acknowledgement!=0 && service.acknowledgement_expiry==0", "pretty": true }'
 
 {
     "results": [
@@ -703,8 +792,9 @@ If attributes are of the Dictionary type, you can also use the indexer format. T
 Example for creating the new host object `example.localdomain`:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
--d '{ "templates": [ "generic-host" ], "attrs": { "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" }, "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
+ -d '{ "templates": [ "generic-host" ], "attrs": { "address": "192.168.1.1", "check_command": "hostalive", "vars.os" : "Linux" }, "pretty": true }'
 {
     "results": [
         {
@@ -720,8 +810,9 @@ contains a detailed error message. The following example is missing the `check_c
 which is required for host objects:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
--d '{ "attrs": { "address": "192.168.1.1", "vars.os" : "Linux" }, "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X PUT 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
+ -d '{ "attrs": { "address": "192.168.1.1", "vars.os" : "Linux" }, "pretty": true }'
 {
     "results": [
         {
@@ -738,15 +829,17 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localh
 Service objects must be created using their full name ("hostname!servicename") referencing an existing host object:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/services/example.localdomain!realtime-load' \
--d '{ "templates": [ "generic-service" ], "attrs": { "check_command": "load", "check_interval": 1,"retry_interval": 1 } }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X PUT 'https://localhost:5665/v1/objects/services/example.localdomain!realtime-load' \
+ -d '{ "templates": [ "generic-service" ], "attrs": { "check_command": "load", "check_interval": 1,"retry_interval": 1 } }'
 ```
 
 Example for a new CheckCommand object:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X PUT 'https://localhost:5665/v1/objects/checkcommands/mytest' \
--d '{ "templates": [ "plugin-check-command" ], "attrs": { "command": [ "/usr/local/sbin/check_http" ], "arguments": { "-I": "$mytest_iparam$" } } }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X PUT 'https://localhost:5665/v1/objects/checkcommands/mytest' \
+ -d '{ "templates": [ "plugin-check-command" ], "attrs": { "command": [ "/usr/local/sbin/check_http" ], "arguments": { "-I": "$mytest_iparam$" } } }'
 ```
 
 ### Modifying Objects <a id="icinga2-api-config-objects-modify"></a>
@@ -758,20 +851,22 @@ parameters need to be passed inside the JSON body:
   -----------|------------|---------------------------
   attrs      | Dictionary | **Required.** Set specific object attributes for this [object type](09-object-types.md#object-types).
 
-In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) should be provided.
+In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters)
+parameter should be provided.
 
 > **Note**:
 >
 > Modified attributes do not trigger a re-evaluation of existing
 > static [apply rules](03-monitoring-basics.md#using-apply) and [group assignments](03-monitoring-basics.md#group-assign-intro).
-> Delete and re-create the objects if you require such changes.
+> Delete and re-create the objects if you require such changes or
+> consider funding [this feature request](https://github.com/Icinga/icinga2/issues/4084).
 >
 > Furthermore you cannot modify templates which have already been resolved
 > during [object creation](12-icinga2-api.md#icinga2-api-config-objects-create).
 > There are attributes which can only be set for [PUT requests](12-icinga2-api.md#icinga2-api-config-objects-create) such as `groups`
 > or `zone`. A complete list of `no_user_modify` attributes can be fetched from the [types](12-icinga2-api.md#icinga2-api-types) URL endpoint.
 
-If attributes are of the Dictionary type, you can also use the indexer format:
+If attributes are of the [Dictionary](17-language-reference.md#dictionary) type, you can also use the indexer format:
 
 ```
 "attrs": { "vars.os": "Linux" }
@@ -780,8 +875,9 @@ If attributes are of the Dictionary type, you can also use the indexer format:
 The following example updates the `address` attribute and the custom attribute `os` for the `example.localdomain` host:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
--d '{ "attrs": { "address": "192.168.1.2", "vars.os" : "Windows" }, "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/objects/hosts/example.localdomain' \
+ -d '{ "attrs": { "address": "192.168.1.2", "vars.os" : "Windows" }, "pretty": true }'
 {
     "results": [
         {
@@ -808,7 +904,8 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
 Example for deleting the host object `example.localdomain`:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE 'https://localhost:5665/v1/objects/hosts/example.localdomain?cascade=1&pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X DELETE 'https://localhost:5665/v1/objects/hosts/example.localdomain?cascade=1&pretty=1'
 {
     "results": [
         {
@@ -851,8 +948,10 @@ The `filter` attribute is passed inside the request body thus requiring to use [
 here.
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5661/v1/templates/hosts' \
--d '{ "filter": "match(\"g*\", tmpl.name)" }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -H 'X-HTTP-Method-Override: GET' -X POST \
+ 'https://localhost:5661/v1/templates/hosts' \
+ -d '{ "filter": "match(\"g*\", tmpl.name)" }'
 ```
 
 Instead of using a filter you can optionally specify the template name in the
@@ -885,8 +984,10 @@ The `filter` attribute is passed inside the request body thus requiring to use [
 here.
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -H 'X-HTTP-Method-Override: GET' -X POST 'https://localhost:5661/v1/variables' \
--d '{ "filter": "variable.type in [ \"String\", \"Number\" ]" }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -H 'X-HTTP-Method-Override: GET' -X POST \
+ 'https://localhost:5661/v1/variables' \
+ -d '{ "filter": "variable.type in [ \"String\", \"Number\" ]" }'
 ```
 
 Instead of using a filter you can optionally specify the variable name in the
@@ -903,10 +1004,12 @@ The result set contains the type, name and value of the global variable.
 There are several actions available for Icinga 2 provided by the `/v1/actions`
 URL endpoint. You can run actions by sending a `POST` request.
 
-In case you have been using the [external commands](14-features.md#external-commands)
-in the past, the API actions provide a similar interface with filter
-capabilities for some of the more common targets which do not directly change
-the configuration.
+The following actions are also used by [Icinga Web 2](https://icinga.com/products/icinga-web-2/):
+
+* sending check results to Icinga from scripts, remote agents, etc.
+* scheduling downtimes from external scripts or cronjobs
+* acknowledging problems
+* adding comments
 
 All actions return a 200 `OK` or an appropriate error code for each
 action performed on each object matching the supplied filter.
@@ -917,7 +1020,9 @@ notification on a program-wide basis must be applied by updating the
 called `app`.
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/objects/icingaapplications/app' -d '{ "attrs": { "enable_notifications": false } }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/objects/icingaapplications/app' \
+ -d '{ "attrs": { "enable_notifications": false } }'
 ```
 
 ### process-check-result <a id="icinga2-api-actions-process-check-result"></a>
@@ -939,30 +1044,33 @@ Send a `POST` request to the URL endpoint `/v1/actions/process-check-result`.
 
 In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
 
-Example for the service `passive-ping6`:
+Example for the service `passive-ping`:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/process-check-result?service=example.localdomain!passive-ping6' \
--d '{ "exit_status": 2, "plugin_output": "PING CRITICAL - Packet loss = 100%", "performance_data": [ "rta=5000.000000ms;3000.000000;5000.000000;0.000000", "pl=100%;80;100;0" ], "check_source": "example.localdomain", "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/process-check-result' \
+-d '{ "type": "Service", "filter": "host.name==\"icinga2-master1.localdomain\" && service.name==\"passive-ping\"", "exit_status": 2, "plugin_output": "PING CRITICAL - Packet loss = 100%", "performance_data": [ "rta=5000.000000ms;3000.000000;5000.000000;0.000000", "pl=100%;80;100;0" ], "check_source": "example.localdomain", "pretty": true }'
 
 {
     "results": [
         {
             "code": 200.0,
-            "status": "Successfully processed check result for object 'localdomain!passive-ping6'."
+            "status": "Successfully processed check result for object 'icinga2-master1.localdomain!passive-ping'."
         }
     ]
 }
 ```
 
+You can avoid URL encoding of white spaces in object names by using the `filter` attribute in the request body.
+
 Example for using the `Host` type and filter by the host name:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/process-check-result' \
--d '{ "filter": "host.name==\"example.localdomain\"", "type": "Host", "exit_status": 1, "plugin_output": "Host is not available." }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/process-check-result' \
+ -d '{ "filter": "host.name==\"example.localdomain\"", "type": "Host", "exit_status": 1, "plugin_output": "Host is not available." }'
 ```
 
-You can avoid URL encoding of white spaces in object names by using the `filter` attribute in the request body.
 
 > **Note**
 >
@@ -988,14 +1096,15 @@ The example reschedules all services with the name "ping6" to immediately perfor
 allowed for the service (`force=true`).
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/reschedule-check' \
--d '{ "type": "Service", "filter": "service.name==\"ping6\"", "force": true, "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/reschedule-check' \
+ -d '{ "type": "Service", "filter": "service.name==\"ping6\"", "force": true, "pretty": true }'
 
 {
     "results": [
         {
             "code": 200.0,
-            "status": "Successfully rescheduled check for object 'example.localdomain!ping6'."
+            "status": "Successfully rescheduled check for object 'icinga2-master1.localdomain!ping6'."
         }
     ]
 }
@@ -1020,8 +1129,9 @@ Example for a custom host notification announcing a global maintenance to
 host owners:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/send-custom-notification' \
--d '{ "type": "Host", "author": "icingaadmin", "comment": "System is going down for maintenance", "force": true, "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/send-custom-notification' \
+ -d '{ "type": "Host", "author": "icingaadmin", "comment": "System is going down for maintenance", "force": true, "pretty": true }'
 
 {
     "results": [
@@ -1054,8 +1164,9 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
 Example:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/delay-notification' \
--d '{ "type": "Service", "timestamp": 1446389894, "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/delay-notification' \
+ -d '{ "type": "Service", "timestamp": 1446389894, "pretty": true }'
 
 {
     "results": [
@@ -1093,18 +1204,19 @@ The following example acknowledges all services which are in a hard critical sta
 a notification for them:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/acknowledge-problem?type=Service&filter=service.state==2&service.state_type=1' \
--d '{ "author": "icingaadmin", "comment": "Global outage. Working on it.", "notify": true, "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/acknowledge-problem' \
+ -d '{ "type": "Service", "filter": "service.state==2&service.state_type=1", "author": "icingaadmin", "comment": "Global outage. Working on it.", "notify": true, "pretty": true }'
 
 {
     "results": [
         {
             "code": 200.0,
-            "status": "Successfully acknowledged problem for object 'example2.localdomain!ping4'."
+            "status": "Successfully acknowledged problem for object 'icinga2-satellite1.localdomain!ping4'."
         },
         {
             "code": 200.0,
-            "status": "Successfully acknowledged problem for object 'example.localdomain!ping4'."
+            "status": "Successfully acknowledged problem for object 'icinga2-satellite2.localdomain!ping4'."
         }
 }
 ```
@@ -1112,7 +1224,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local
 ### remove-acknowledgement <a id="icinga2-api-actions-remove-acknowledgement"></a>
 
 Removes the acknowledgements for services or hosts. Once the acknowledgement has
-been removed notifications will be sent out again.
+been removed the next notification will be sent again.
 
 Send a `POST` request to the URL endpoint `/v1/actions/remove-acknowledgement`.
 
@@ -1121,7 +1233,9 @@ A [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid ty
 The example removes all service acknowledgements:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-acknowledgement?type=Service&pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/remove-acknowledgement' \
+ -d '{ "type": "Service", "pretty": true }'
 
 {
     "results": [
@@ -1152,20 +1266,22 @@ In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters
 The following example adds a comment for all `ping4` services:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/add-comment?type=Service&filter=service.name==%22ping4%22' -d '{ "author": "icingaadmin", "comment": "Troubleticket #123456789 opened.", "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/add-comment' \
+ -d '{ "type": "Service", "filter": "service.name==\"ping4\"", "author": "icingaadmin", "comment": "Troubleticket #123456789 opened.", "pretty": true }'
 {
     "results": [
         {
             "code": 200.0,
             "legacy_id": 26.0,
-            "name": "example.localdomain!ping4!example.localdomain-1446824161-0",
-            "status": "Successfully added comment 'example.localdomain!ping4!example.localdomain-1446824161-0' for object 'example.localdomain!ping4'."
+            "name": "icinga2-satellite1.localdomain!ping4!7e7861c8-8008-4e8d-9910-2a0bb26921bd",
+            "status": "Successfully added comment 'icinga2-satellite1.localdomain!ping4!7e7861c8-8008-4e8d-9910-2a0bb26921bd' for object 'icinga2-satellite1.localdomain!ping4'."
         },
         {
             "code": 200.0,
             "legacy_id": 27.0,
-            "name": "example2.localdomain!ping4!example.localdomain-1446824161-1",
-            "status": "Successfully added comment 'example2.localdomain!ping4!example.localdomain-1446824161-1' for object 'example2.localdomain!ping4'."
+            "name": "icinga2-satellite2.localdomain!ping4!9a4c43f5-9407-a536-18bf-4a6cc4b73a9f",
+            "status": "Successfully added comment 'icinga2-satellite2.localdomain!ping4!9a4c43f5-9407-a536-18bf-4a6cc4b73a9f' for object 'icinga2-satellite2.localdomain!ping4'."
         }
     ]
 }
@@ -1185,12 +1301,14 @@ A [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid ty
 Example for a simple filter using the `comment` URL parameter:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-comment?comment=example2.localdomain!ping4!mbmif.local-1446986367-0&pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/remove-comment' \
+ -d '{ "comment": "icinga2-satellite2.localdomain!ping4!9a4c43f5-9407-a536-18bf-4a6cc4b73a9f", "pretty": true }'
 {
     "results": [
         {
             "code": 200.0,
-            "status": "Successfully removed comment 'example2.localdomain!ping4!mbmif.local-1446986367-0'."
+            "status": "Successfully removed comment 'icinga2-satellite2.localdomain!ping4!9a4c43f5-9407-a536-18bf-4a6cc4b73a9f'."
         }
     ]
 }
@@ -1199,16 +1317,18 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local
 Example for removing all service comments using a service name filter for `ping4`:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-comment?filter=service.name==%22ping4%22&type=Service&pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/remove-comment'
+ -d '{ "type": "Service", "filter": "service.name==\"ping4\"", "pretty": true }'
 {
     "results": [
         {
             "code": 200.0,
-            "status": "Successfully removed all comments for object 'example2.localdomain!ping4'."
+            "status": "Successfully removed all comments for object 'icinga2-satellite1.localdomain!ping4'."
         },
         {
             "code": 200.0,
-            "status": "Successfully removed all comments for object 'example.localdomain!ping4'."
+            "status": "Successfully removed all comments for object 'icinga2-satellite2.localdomain!ping4'."
         }
     ]
 }
@@ -1233,28 +1353,37 @@ Send a `POST` request to the URL endpoint `/v1/actions/schedule-downtime`.
 
 In addition to these parameters a [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid types for this action are `Host` and `Service`.
 
-Example:
+Example for scheduling a downtime for all `ping4` services:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/schedule-downtime?type=Service&filter=service.name==%22ping4%22' -d '{ "start_time": 1446388806, "end_time": 1446389806, "duration": 1000, "author": "icingaadmin", "comment": "IPv4 network maintenance", "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/schedule-downtime' \
+ -d '{ "type": "Service", "filter": "service.name==\"ping4\"", "start_time": 1446388806, "end_time": 1446389806, "duration": 1000, "author": "icingaadmin", "comment": "IPv4 network maintenance", "pretty": true }'
 {
     "results": [
         {
             "code": 200.0,
             "legacy_id": 2.0,
-            "name": "example2.localdomain!ping4!example.localdomain-1446822004-0",
-            "status": "Successfully scheduled downtime 'example2.localdomain!ping4!example.localdomain-1446822004-0' for object 'example2.localdomain!ping4'."
+            "name": "icinga2-satellite1.localdomain!ping4!ecc5fa55-a5b8-4189-a013-a5d4bb47af34",
+            "status": "Successfully scheduled downtime 'icinga2-satellite1.localdomain!ping4!ecc5fa55-a5b8-4189-a013-a5d4bb47af34' for object 'icinga2-satellite1.localdomain!ping4'."
         },
         {
             "code": 200.0,
             "legacy_id": 3.0,
-            "name": "example.localdomain!ping4!example.localdomain-1446822004-1",
-            "status": "Successfully scheduled downtime 'example.localdomain!ping4!example.localdomain-1446822004-1' for object 'example.localdomain!ping4'."
+            "name": "icinga2-satellite2.localdomain!ping4!abc59032-4589-abcd-4567-ecf67856c347",
+            "status": "Successfully scheduled downtime 'icinga2-satellite2.localdomain!ping4!abc59032-4589-abcd-4567-ecf67856c347' for object 'icinga2-satellite2.localdomain!ping4'."
         }
     ]
 }
 ```
 
+In case you want to target just a single service on a host, modify the filter
+like this:
+
+```
+"filter": "host.name==\"icinga2-satellite1.localdomain\" && service.name==\"ping4\""
+```
+
 ### remove-downtime <a id="icinga2-api-actions-remove-downtime"></a>
 
 Remove the downtime using its `name` attribute , returns `OK` if the
@@ -1269,26 +1398,30 @@ A [filter](12-icinga2-api.md#icinga2-api-filters) must be provided. The valid ty
 Example for a simple filter using the `downtime` URL parameter:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime?downtime=example.localdomain!ping4!mbmif.local-1446979168-6&pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/remove-downtime' \
+ -d '{ "downtime": "icinga2-satellite2.localdomain!ping4!abc59032-4589-abcd-4567-ecf67856c347", "pretty": true }'
 {
     "results": [
         {
             "code": 200.0,
-            "status": "Successfully removed downtime 'example.localdomain!ping4!mbmif.local-1446979168-6'."
+            "status": "Successfully removed downtime 'icinga2-satellite2.localdomain!ping4!abc59032-4589-abcd-4567-ecf67856c347'."
         }
     ]
 }
 ```
 
-Example for removing all host downtimes using a host name filter for `example.localdomain`:
+Example for removing all host downtimes using a host name filter for `icinga2-satellite2.localdomain`:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime?filter=host.name==%22example.localdomain%22&type=Host&pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/remove-downtime' \
+ -d '{ "type": "Host", "filter": "host.name==\"icinga2-satellite2.localdomain\"", "pretty": true }'
 {
     "results": [
         {
             "code": 200.0,
-            "status": "Successfully removed all downtimes for object 'example.localdomain'."
+            "status": "Successfully removed all downtimes for object 'icinga2-satellite2.localdomain'."
         }
     ]
 }
@@ -1298,12 +1431,13 @@ Example for removing a downtime from a host but not the services filtered by the
 filter variables explained in the [advanced filters](12-icinga2-api.md#icinga2-api-advanced-filters) chapter.
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/remove-downtime' \
-        -d $'{
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/remove-downtime' \
+ -d $'{
   "type": "Downtime",
   "filter": "host.name == filterHost && !service && downtime.author == filterAuthor",
   "filter_vars": {
-    "filterHost": "example.localdomain",
+    "filterHost": "icinga2-satellite1.localdomain",
     "filterAuthor": "icingaadmin"
   },
   "pretty": true
@@ -1313,7 +1447,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local
     "results": [
         {
             "code": 200.0,
-            "status": "Successfully removed downtime 'example.localdomain!mbmif.local-1463043129-3'."
+            "status": "Successfully removed downtime 'icinga2-satellite1.localdomain!ecc5fa55-a5b8-ef34-abcd-a5d41234af34'."
         }
     ]
 }
@@ -1321,7 +1455,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local
 
 ### shutdown-process <a id="icinga2-api-actions-shutdown-process"></a>
 
-Shuts down Icinga2. May or may not return.
+Shuts down Icinga. May or may not return.
 
 Send a `POST` request to the URL endpoint `/v1/actions/shutdown-process`.
 
@@ -1330,7 +1464,8 @@ This action does not support a target type or filter.
 Example:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/shutdown-process?pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/shutdown-process?pretty=1'
 
 {
     "results": [
@@ -1344,7 +1479,7 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local
 
 ### restart-process <a id="icinga2-api-actions-restart-process"></a>
 
-Restarts Icinga2. May or may not return.
+Restarts Icinga. May or may not return.
 
 Send a `POST` request to the URL endpoint `/v1/actions/restart-process`.
 
@@ -1353,7 +1488,8 @@ This action does not support a target type or filter.
 Example:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/restart-process?pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/restart-process?pretty=1'
 
 {
     "results": [
@@ -1370,6 +1506,12 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local
 Generates a PKI ticket for [CSR auto-signing](06-distributed-monitoring.md#distributed-monitoring-setup-csr-auto-signing).
 This can be used in combination with satellite/client setups requesting this ticket number.
 
+> **Note**
+>
+> This must be used on the local host, or e.g. by a Puppet master.
+> Doing so remotely may result in security issues with cluster
+> trust relationships.
+
 Send a `POST` request to the URL endpoint `/v1/actions/generate-ticket`.
 
   Parameter     | Type      | Description
@@ -1379,8 +1521,9 @@ Send a `POST` request to the URL endpoint `/v1/actions/generate-ticket`.
 Example:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/actions/generate-ticket' \
--d '{ "cn": "icinga2-client1.localdomain", "pretty": true }'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/actions/generate-ticket' \
+ -d '{ "cn": "icinga2-client1.localdomain", "pretty": true }'
 {
     "results": [
         {
@@ -1394,6 +1537,14 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local
 
 ## Event Streams <a id="icinga2-api-event-streams"></a>
 
+Event streams can be used to receive check results, downtimes, comments,
+acknowledgements, etc. as a "live stream" from Icinga.
+
+You can for example forward these types into your own backend. Process the
+metrics and correlate them with notifications and state changes e.g. in Elasticsearch
+with the help of [Icingabeat](https://icinga.com/docs/icingabeat/latest/). Another use
+case are aligned events and creating/resolving tickets automatically in your ticket system.
+
 You can subscribe to event streams by sending a `POST` request to the URL endpoint `/v1/events`.
 The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body):
 
@@ -1428,6 +1579,8 @@ Example for all downtime events:
 
 ```
 &types=DowntimeAdded&types=DowntimeRemoved&types=DowntimeTriggered
+
+-d '{ "types": ["DowntimeAdded", "DowntimeRemoved", "DowntimeTriggered"] }'
 ```
 
 #### <a id="icinga2-api-event-streams-type-checkresult"></a> Event Stream Type: CheckResult
@@ -1568,6 +1721,8 @@ Example for the `CheckResult` type with the `exit_code` set to `2`:
 
 ```
 &types=CheckResult&filter=event.check_result.exit_status==2
+
+-d '{ "types": "CheckResult", "filter": "event.check_result.exit_status==2" }'
 ```
 
 Example for the `CheckResult` type with the service [matching](18-library-reference.md#global-functions-match)
@@ -1575,6 +1730,8 @@ the string pattern "random\*":
 
 ```
 &types=CheckResult&filter=match%28%22random*%22,event.service%29
+
+-d { "types": "CheckResult", "filter": "match(\"random*\", event.service)" }
 ```
 
 ### Event Stream Response <a id="icinga2-api-event-streams-response"></a>
@@ -1585,7 +1742,9 @@ must support long-polling and HTTP/1.1. HTTP/1.0 is not supported.
 Example:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/events?queue=michi&types=CheckResult&filter=event.check_result.exit_status==2'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/events' \
+ -d '{ "queue": "myqueue", "types": "CheckResult", "filter": "event.check_result.exit_status==2" }'
 
 {"check_result":{ ... },"host":"example.localdomain","service":"ping4","timestamp":1445421319.7226390839,"type":"CheckResult"}
 {"check_result":{ ... },"host":"example.localdomain","service":"ping4","timestamp":1445421324.7226390839,"type":"CheckResult"}
@@ -1649,23 +1808,30 @@ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/status/IcingaApplication?
 
 ## Configuration Management <a id="icinga2-api-config-management"></a>
 
-The main idea behind configuration management is to allow external applications
-creating configuration packages and stages based on configuration files and
+The main idea behind configuration management is that external applications
+can create configuration packages and stages based on configuration files and
 directory trees. This replaces any additional SSH connection and whatnot to
 dump configuration files to Icinga 2 directly.
+
 In case you are pushing a new configuration stage to a package, Icinga 2 will
 validate the configuration asynchronously and populate a status log which
-can be fetched in a separated request.
+can be fetched in a separated request. Once the validation succeeds,
+a reload is triggered by default.
+
+This functionality was primarly developed for the [Icinga Director](https://icinga.com/docs/director/latest/)
+but can be used with your own deployments too. It also solves the problem
+with certain runtime objects (zones, endpoints) and can be used to
+deploy global templates in [global cluster zones](06-distributed-monitoring.md#distributed-monitoring-global-zone-config-sync).
 
 
-### Creating a Config Package <a id="icinga2-api-config-management-create-package"></a>
+### Create a Config Package <a id="icinga2-api-config-management-create-package"></a>
 
 Send a `POST` request to a new config package called `example-cmdb` in this example. This
-will create a new empty configuration package.
+creates a new empty configuration package.
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
-'https://localhost:5665/v1/config/packages/example-cmdb?pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+-X POST 'https://localhost:5665/v1/config/packages/example-cmdb?pretty=1'
 {
     "results": [
         {
@@ -1677,12 +1843,20 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
 }
 ```
 
-Package names starting with an underscore are reserved for internal packages and must not be used.
+Package names with the `_` prefix are reserved for internal packages and must not be used.
+You can recognize `_api`, `_etc` and `_cluster` when querying specific objects and packages.
 
-### Uploading configuration for a Config Package <a id="icinga2-api-config-management-create-config-stage"></a>
+Each configuration object stores the package source in the `package` attribute.
 
-Configuration files in packages are managed in stages.
-Stages provide a way to maintain multiple configuration versions for a package.
+### Create a Stage: Upload Configuration <a id="icinga2-api-config-management-create-config-stage"></a>
+
+Configuration files in packages are managed in stages. Stages provide a way
+to maintain multiple configuration versions for a package. Once a new stage
+is deployed, the content is validated and set as active stage on success.
+
+On failure, the older stage remains active, and the caller can fetch the `startup.log`
+from this stage deployment attempt to see what exactly failed. You can see that
+in the Director's deployment log.
 
 Send a `POST` request to the URL endpoint `/v1/config/stages` and add the name of an existing
 configuration package to the URL path (e.g. `example-cmdb`).
@@ -1723,8 +1897,8 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST \
         {
             "code": 200.0,
             "package": "example-cmdb",
-            "stage": "example.localdomain-1441625839-0",
-            "status": "Created stage. Icinga2 will reload."
+            "stage": "7e7861c8-8008-4e8d-9910-2a0bb26921bd",
+            "status": "Created stage. Reload triggered."
         }
     ]
 }
@@ -1742,7 +1916,7 @@ and its configuration objects will remain active.
 >
 > Old stages are not purged automatically. You can [remove stages](12-icinga2-api.md#icinga2-api-config-management-delete-config-stage) that are no longer in use.
 
-Icinga 2 will create the following files in the configuration package
+Icinga 2 creates the following files in the configuration package
 stage after configuration validation:
 
   File        | Description
@@ -1751,7 +1925,8 @@ stage after configuration validation:
   startup.log | Contains the [configuration validation](11-cli-commands.md#config-validation) output.
 
 You can [fetch these files](12-icinga2-api.md#icinga2-api-config-management-fetch-config-package-stage-files)
-in order to verify that the new configuration was deployed successfully.
+in order to verify that the new configuration was deployed successfully. Please follow the chapter below
+to learn more about this.
 
 
 ### List Configuration Packages and their Stages <a id="icinga2-api-config-management-list-config-packages"></a>
@@ -1769,7 +1944,7 @@ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/packages?pretty=1'
             "active-stage": "",
             "name": "example-cmdb",
             "stages": [
-                "example.localdomain-1441625839-0"
+                "7e7861c8-8008-4e8d-9910-2a0bb26921bd"
             ]
         }
     ]
@@ -1780,10 +1955,10 @@ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/packages?pretty=1'
 
 In order to retrieve a list of files for a stage you can send a `GET` request to
 the URL endpoint `/v1/config/stages`. You need to include
-the package name (`example-cmdb`) and stage name (`example.localdomain-1441625839-0`) in the URL:
+the package name (`example-cmdb`) and stage name (`7e7861c8-8008-4e8d-9910-2a0bb26921bd`) in the URL:
 
 ```
-$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441625839-0?pretty=1'
+$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/stages/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd?pretty=1'
 {
     "results": [
 ...
@@ -1823,7 +1998,7 @@ the package name, the stage name and the relative path to the file to the URL pa
 The following example fetches the configuration file `conf.d/test.conf`:
 
 ```
-$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/example.localdomain-1441625839-0/conf.d/test.conf'
+$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd/conf.d/test.conf'
 
 object Host "cmdb-host" { chec_command = "dummy" }
 ```
@@ -1841,18 +2016,18 @@ by sending a `GET` request to the URL endpoint `/v1/config/files`. You must incl
 the package name, stage name and the `startup.log` in the URL path.
 
 ```
-$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/example.localdomain-1441133065-1/startup.log'
+$ curl -k -s -u root:icinga 'https://localhost:5665/v1/config/files/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd/startup.log'
 ...
 
 critical/config: Error: Attribute 'chec_command' does not exist.
 Location:
-/var/lib/icinga2/api/packages/example-cmdb/example.localdomain-1441133065-1/conf.d/test.conf(1): object Host "cmdb-host" { chec_command = "dummy" }
+/var/lib/icinga2/api/packages/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd/conf.d/test.conf(1): object Host "cmdb-host" { chec_command = "dummy" }
                                                                                                        ^^^^^^^^^^^^^^^^^^^^^^
 
 critical/config: 1 error
 ```
 
-The output is similar to the manual [configuration validation](11-cli-commands.md#config-validation).
+The output is the exact as known from [configuration validation](11-cli-commands.md#config-validation).
 
 > **Note**
 >
@@ -1865,12 +2040,12 @@ You can send a `DELETE` request to the URL endpoint `/v1/config/stages`
 in order to purge a configuration stage. You must include the package and
 stage name inside the URL path.
 
-The following example removes the failed configuration stage `example.localdomain-1441133065-1`
+The following example removes the failed configuration stage `7e7861c8-8008-4e8d-9910-2a0bb26921bd`
 in the `example-cmdb` configuration package:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X DELETE \
-'https://localhost:5665/v1/config/stages/example-cmdb/example.localdomain-1441133065-1?pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X DELETE 'https://localhost:5665/v1/config/stages/example-cmdb/7e7861c8-8008-4e8d-9910-2a0bb26921bd?pretty=1'
 {
     "results": [
         {
@@ -1954,11 +2129,17 @@ $ curl -k -s -u root:icinga 'https://localhost:5665/v1/types/Object?pretty=1'
 }
 ```
 
-## Console <a id="icinga2-api-console"></a>
+## Debug Console <a id="icinga2-api-console"></a>
 
 You can inspect variables and execute other expressions by sending a `POST` request to the URL endpoint `/v1/console/execute-script`.
 In order to receive auto-completion suggestions, send a `POST` request to the URL endpoint `/v1/console/auto-complete-script`.
 
+> **Note**
+>
+> This functionality is used by the [debug console](11-cli-commands.md#cli-command-console). Do not use this in production, unless
+> you are aware of the fact that expressions and commands may crash the daemon, or lead into
+> unwanted behaviour. Use this URL endpoint **read-only** when needed.
+
 The following parameters need to be specified (either as URL parameters or in a JSON-encoded message body):
 
   Parameter  | Type         | Description
@@ -1980,7 +2161,8 @@ If you specify a session identifier, the same script context can be reused for m
 Example for fetching the command line from the local host's last check result:
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/console/execute-script?command=get_host(NodeName).last_check_result.command&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756&pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/console/execute-script?command=get_host(NodeName).last_check_result.command&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756&pretty=1'
 {
     "results": [
         {
@@ -2004,7 +2186,8 @@ Example for fetching auto-completion suggestions for the `Host.` type. This work
 similar fashion when pressing TAB inside the [console CLI command](11-cli-commands.md#cli-command-console):
 
 ```
-$ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://localhost:5665/v1/console/auto-complete-script?command=Host.&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756&pretty=1'
+$ curl -k -s -u root:icinga -H 'Accept: application/json' \
+ -X POST 'https://localhost:5665/v1/console/auto-complete-script?command=Host.&sandboxed=0&session=bb75fd7c-c686-407d-9688-582c04227756&pretty=1'
 {
     "results": [
         {
@@ -2027,27 +2210,92 @@ $ curl -k -s -u root:icinga -H 'Accept: application/json' -X POST 'https://local
 
 ## API Clients <a id="icinga2-api-clients"></a>
 
-There are a couple of existing clients which can be used with the Icinga 2 API:
+After its initial release in 2015, community members
+and developers have been working hard to add more REST API
+clients and integrations into DevOps tools.
 
-* [curl](https://curl.haxx.se/) or any other HTTP client really
-* [Icinga 2 console (CLI command)](12-icinga2-api.md#icinga2-api-clients-cli-console)
-* [Icinga Web 2 Director](https://icinga.com/products/icinga-web-2-modules/)
-
-Demo cases:
-
-* [Dashing](https://github.com/Icinga/dashing-icinga2)
-* [API examples](https://github.com/Icinga/icinga2-api-examples)
+* [Libraries](12-icinga2-api.md#icinga2-api-clients-libraries)
+* [Status](#icinga2-api-clients-status)
+* [Management](#icinga2-api-clients-management)
+* [Event Streams](#icinga2-api-clients-event-streams)
+* [Actions](#icinga2-api-clients-actions)
+* [REST API Apps](#icinga2-api-clients-apps)
 
 Additional [programmatic examples](12-icinga2-api.md#icinga2-api-clients-programmatic-examples)
 will help you getting started using the Icinga 2 API in your environment.
 
-### Icinga 2 Console <a id="icinga2-api-clients-cli-console"></a>
+### Libraries <a id="icinga2-api-clients-libraries"></a>
 
-By default the [console CLI command](11-cli-commands.md#cli-command-console) evaluates
-expressions in a local interpreter, i.e. independently from your Icinga 2 daemon.
-Add the `--connect` parameter to debug and evaluate expressions via the API.
+Name												| Language	| Description
+------------------------------------------------------------------------------------------------|---------------|--------------------------------------------------------
+[ruby-icinga2](https://github.com/bodsch/ruby-icinga2)                                          | Ruby          | Ruby library
+[python-icinga2_api](https://github.com/KevinHonka/Icinga2_Python_API)                          | Python        | Python library
+[python-icinga2-api](https://github.com/fmnisme/python-icinga2api)				| Python	| Python bindings for Icinga 2 interaction
+[go-icinga2](https://github.com/xert/go-icinga2)						| Golang	| Golang functions and type definitions
+[go-icinga2-api](https://github.com/lrsmith/go-icinga2-api/)					| Golang	| Golang implementation used inside the Terraform provider
+[go-icinga2-client](https://github.com/Nexinto/go-icinga2-client)     | Golang  | Golang implementation for the Rancher integration.
+[Monitoring::Icinga2::Client::REST](https://metacpan.org/release/THESEAL/Monitoring-Icinga2-Client-REST-2.0.0) | Perl | Perl bindings.
+[Icinga 2 API in PHP](https://github.com/uniwue-rz/icinga2-api)					| PHP		| PHP implementation. For other examples, look into Icinga Web 2 and Director.
 
-### API Clients Programmatic Examples <a id="icinga2-api-clients-programmatic-examples"></a>
+### Status <a id="icinga2-api-clients-status"></a>
+
+Name												| Language	| Description
+------------------------------------------------------------------------------------------------|---------------|--------------------------------------------------------
+[Dashing](https://github.com/dnsmichi/dashing-icinga2)						| Ruby, HTML	| Dashboard for Dashing querying the REST API for current host/service/global status
+[InfluxDB Telegraf Input](https://github.com/influxdata/telegraf/blob/master/plugins/inputs/icinga2/README.md) | Golang	| [Telegraf](https://github.com/influxdata/telegraf) is an agent written in Go for collecting, processing, aggregating, and writing metrics.
+[Icinga 2 Slack Bot](https://github.com/mlabouardy/icinga2-slack-bot) 				| Golang | Query host/service details from a [Slack](https://slack.com/) channel
+[icinga2bot](https://github.com/reikoNeko/icinga2bot)						| Python	| [Errbot](http://errbot.io/en/latest/user_guide/setup.html) plugin to fetch status and event stream information and forward to XMPP, IRC, etc.
+[IcingaBusyLightAgent](https://github.com/stdevel/IcingaBusylightAgent) 			| C#		| Notification Agent in Systray
+[BitBar for OSX](https://getbitbar.com/plugins/Dev/Icinga2/icinga2.24m.py)			| Python	| macOS tray app for highlighting the host/service status
+[Icinga 2 Multistatus](https://chrome.google.com/webstore/detail/icinga-multi-status/khabbhcojgkibdeipanmiphceeoiijal/related)	| - 	| Chrome Extension
+
+### Manage Objects <a id="icinga2-api-clients-management"></a>
+
+Name												| Language	| Description
+------------------------------------------------------------------------------------------------|---------------|--------------------------------------------------------
+[Icinga Director](https://icinga.com/docs/director/latest) 					| PHP, JS	| Icinga 2 configuration interface with a nice frontend, and automated imports for nearly any source.
+[Terraform Provider](https://github.com/terraform-providers/terraform-provider-icinga2)		| Golang	| Register hosts from Terraform in Icinga 2. [Official docs](https://www.terraform.io/docs/providers/icinga2/index.html).
+[Kube Icinga](https://github.com/gyselroth/kube-icinga)			                        | Typescript    | Monitor Kubernetes services / resources using icinga2 (including autodiscovery support)
+[Logstash output for Icinga](https://www.icinga.com/products/integrations/elastic/)             | Ruby          | Forward check results and create objects from log events
+[Foreman Smart Proxy Monitoring](https://github.com/theforeman/smart_proxy_monitoring)		| Ruby		| Smart Proxy extension for Foreman creating and deleting hosts and services in Icinga 2
+[Rancher integration](https://github.com/Nexinto/rancher-icinga)         		        | Golang        | Registers [Rancher](http://rancher.com/rancher/) resources in Icinga 2 for monitoring.
+[AWS/EC2](https://github.com/Icinga/icinga2-api-examples/tree/master/aws-ec2)			| Ruby		| Example script for creating and deleting AWS instances in Icinga 2
+[Ansible Host Module](https://docs.ansible.com/ansible/latest/modules/icinga2_host_module.html) | Python 	| In progress, [Ansible Feature](https://docs.ansible.com/ansible/latest/modules/icinga2_feature_module.html#icinga2-feature-module) is also there.
+
+### Event Streams <a id="icinga2-api-clients-event-streams"></a>
+
+Name												| Language	| Description
+------------------------------------------------------------------------------------------------|---------------|--------------------------------------------------------
+[Elastic Icingabeat](https://icinga.com/docs/icingabeat/latest/)				| Golang	| Process events and send to Elasticsearch/Logstash outputs
+[Request Tracker ticket integration](https://github.com/bytemine/icinga2rt)			| Golang	| Create and update RT tickets
+[Logstash input event stream](https://github.com/bobapple/logstash-input-icinga_eventstream)	| Ruby		| Forward events as Logstash input
+[Flapjack events](https://github.com/sol1/flapjack-icinga2)					| Golang	| Dumping events into Redis for Flapjack processing
+[Stackstorm integration](https://github.com/StackStorm-Exchange/stackstorm-icinga2)		| Python	| Processing events and fetching status information
+
+### Actions <a id="icinga2-api-clients-actions"></a>
+
+Name												| Language	| Description
+------------------------------------------------------------------------------------------------|---------------|--------------------------------------------------------
+[Icinga Web 2](https://icinga.com/docs/icingaweb2/latest/)                                      | PHP           | Trigger actions via command transport
+[Logstash output for Icinga](https://www.icinga.com/products/integrations/elastic/)             | Ruby          | Forward check results and create objects from log events
+[OTRS SystemMonitoring](https://github.com/OTRS/SystemMonitoring)                               | Perl          | Acknowledge problems in Icinga 2 from OTRS tickets
+[mqttwarn](https://github.com/jpmens/mqttwarn#icinga2)						| Python	| Forward check results from mqttwarn to Icinga 2
+[Lita handler](https://github.com/tuxmea/lita-icinga2)						| Ruby		| List, recheck and acknowledge through a #chatops bot called [Lita](https://github.com/litaio/lita)
+[Sakuli forwarder](http://sakuli.readthedocs.io/en/latest/forwarder-icinga2api/)		| Java		| Forward check results from tests from [Sakuli](https://github.com/ConSol/sakuli) to Icinga 2
+[OpsGenie actions](https://www.opsgenie.com/docs/integrations/icinga2-integration)		| Golang, Java	| Integrate Icinga 2 into OpsGenie
+
+
+### REST API Apps <a id="icinga2-api-clients-apps"></a>
+
+Name												| Language	| Description
+------------------------------------------------------------------------------------------------|---------------|--------------------------------------------------------
+Browser plugins											| -		| [Postman for Chrome](https://www.getpostman.com), [RESTED for Firefox](https://addons.mozilla.org/en-US/firefox/addon/rested/)
+[Postman](https://www.getpostman.com/)                                                          | -             | App instead of browser plugin
+[Cocoa Rest Client](http://mmattozzi.github.io/cocoa-rest-client/)                              | -             | macOS app
+[Paw for MacOS](https://paw.cloud)								| (exported)	| Paw is a full-featured HTTP client that lets you test and describe the APIs you build or consume. It has a beautiful native macOS interface to compose requests, inspect server responses, generate client code and export API definitions.
+
+
+### Programmatic Examples <a id="icinga2-api-clients-programmatic-examples"></a>
 
 The following languages are covered:
 
@@ -2057,11 +2305,10 @@ The following languages are covered:
 * [Perl](12-icinga2-api.md#icinga2-api-clients-programmatic-examples-perl)
 * [Golang](12-icinga2-api.md#icinga2-api-clients-programmatic-examples-golang)
 
-The [request method](icinga2-api-requests) is `POST` using
-[X-HTTP-Method-Override: GET](12-icinga2-api.md#icinga2-api-requests-method-override)
-which allows you to send a JSON request body. The examples request
-specific service attributes joined with host attributes. `attrs`
-and `joins` are therefore specified as array.
+The [request method](icinga2-api-requests) is `POST` using [X-HTTP-Method-Override: GET](12-icinga2-api.md#icinga2-api-requests-method-override)
+which allows you to send a JSON request body. The examples request specific service
+attributes joined with host attributes. `attrs` and `joins` are therefore specified
+as array.
 The `filter` attribute [matches](18-library-reference.md#global-functions-match)
 on all services with `ping` in their name.
 
diff --git a/doc/19-technical-concepts.md b/doc/19-technical-concepts.md
index eefeb4a26..878e5391f 100644
--- a/doc/19-technical-concepts.md
+++ b/doc/19-technical-concepts.md
@@ -1680,7 +1680,7 @@ Message updates are dropped when
 * The origin sender is not in a parent zone of the receiver.
 * The certificate fingerprint is in an invalid format.
 
-#### log::SetLogPosition <a id="technical-concepts-json-rpc-messages-pki-updatecertificate"></a>
+#### log::SetLogPosition <a id="technical-concepts-json-rpc-messages-log-setlogposition"></a>
 
 > Location: `apilistener.cpp` and `jsonrpcconnection.cpp`