diff --git a/modules/monitoring/doc/commandtransports.md b/modules/monitoring/doc/commandtransports.md
index 238643f5c..ba9a3be54 100644
--- a/modules/monitoring/doc/commandtransports.md
+++ b/modules/monitoring/doc/commandtransports.md
@@ -1,24 +1,56 @@
-# <a id="commandtransports"></a> The commandtransports.ini configuration file
+# <a id="commandtransports"></a> External Command Transport Configuration
 
-## Abstract
+## Introduction
 
-The commandtransports.ini defines how Icinga Web 2 accesses the command pipe of
-your Icinga instance in order to submit external commands. Depending on the
-config path (default: /etc/icingaweb2) of your Icinga Web 2 installation you can
-find it under ./modules/monitoring/commandtransports.ini.
+The `commandtransports.ini` defines how Icinga Web 2 transports commands to your Icinga instance in order to submit
+external commands. By default, this file is located at `/etc/icingaweb2/modules/monitoring/commandtransports.ini`.
 
-## Syntax
+You can define multiple command transports in the `commandtransports.ini`. Every transport starts with a section header
+containing its name, followed by the config directives for this transport in the standard INI-format.
 
-You can define multiple command transports in the commandtransports.ini. Every
-transport starts with a section header containing its name, followed by the
-config directives for this transport in the standard INI-format.
+Icinga Web 2 will try one transport after another to send a command until the command is successfully sent.
+If [configured](#commandtransports-multiple-instances), Icinga Web 2 will take different instances into account.
+The order in which Icinga Web 2 processes the configured transports is defined by the order of sections in
+`commandtransports.ini`.
 
-Icinga Web 2 will try one transport after another to send a command, depending
-on the respective Icinga instance, until the command is successfully sent. The
-order in which Icinga Web 2 processes the configured transports is defined by
-the order of sections in the commandtransports.ini.
+## Use the Icinga 2 API
 
-## Using a local command pipe
+If you're running Icinga 2 it's best to use the Icinga 2 API for transmitting external commands.
+
+First, you have to enable the `api` feature on the Icinga 2 host where you want to send the commands to:
+
+```
+icinga2 feature enable api
+```
+
+Next, you have to create an ApiUser object for authenticating against the Icinga 2 API. This configuration also applies
+to the host where you want to send the commands to. We recommend to create/edit the file
+`/etc/icinga2/conf.d/api-users.conf`:
+
+```
+object ApiUser "web2" {
+  password = "bea11beb7b810ea9ce6ea" // Change this!
+  permissions = [ "actions/*", "objects/modify/hosts", "objects/modify/services", "objects/modify/icingaapplications" ]
+}
+```
+
+The permissions `actions/*`, `objects/modify/hosts`, `objects/modify/services`, `objects/modify/icingaapplications` are
+mandatory in order to submit all external commands from within Icinga Web 2.
+
+**Restart Icinga 2** for the changes to take effect.
+
+After that, you have to set up Icinga Web 2's `commandtransport.ini` to use the Icinga 2 API:
+
+```
+[icinga2]
+transport = "api"
+host = "127.0.0.1" // Icinga 2 host
+port = "5665"
+username = "web2"
+password = "bea11beb7b810ea9ce6ea" // Change that!
+```
+
+## Use a Local Command Pipe
 
 A local Icinga instance requires the following directives:
 
@@ -31,7 +63,7 @@ path        = /var/run/icinga2/cmd/icinga2.cmd
 When sending commands to the Icinga instance, Icinga Web 2 opens the file found
 on the local filesystem underneath 'path' and writes the external command to it.
 
-## Using SSH for accessing a remote command pipe
+## Use SSH For a Remote Command Pipe
 
 A command pipe on a remote host's filesystem can be accessed by configuring a
 SSH based command transport and requires the following directives:
@@ -74,11 +106,10 @@ user        = icinga
 private_key = /etc/icingaweb2/ssh/icinga
 ```
 
-## Configuring transports for different Icinga instances
+## <a id="commandtransports-multiple-instances"></a> Configure Transports for Different Icinga Instances
 
-If there are multiple but different Icinga instances writing to your IDO you can
-define which transport belongs to which Icinga instance by providing the
-directive 'instance'. This directive should contain the name of the Icinga
+If there are multiple but different Icinga instances writing to your IDO, you can define which transport belongs to
+which Icinga instance by providing the directive `instance`. This directive should contain the name of the Icinga
 instance you want to assign to the transport:
 
 ```
@@ -91,6 +122,5 @@ instance = icinga1
 instance = icinga2
 ```
 
-Associating a transport to a specific Icinga instance causes this transport to
-be used to send commands to the linked instance only. Transports without a
-linked Icinga instance are utilized to send commands to all instances.
+Associating a transport to a specific Icinga instance causes this transport to be used to send commands to the linked
+instance only. Transports without a linked Icinga instance are used to send commands to all instances.