diff --git a/doc/09-object-types.md b/doc/09-object-types.md
index 8d91b7b30..4945b18ec 100644
--- a/doc/09-object-types.md
+++ b/doc/09-object-types.md
@@ -1385,7 +1385,7 @@ Configuration Attributes:
   fixed                     | Boolean               | **Optional.** Whether this is a fixed downtime. Defaults to `true`.
   duration                  | Duration              | **Optional.** How long the downtime lasts. Only has an effect for flexible (non-fixed) downtimes.
   ranges                    | Dictionary            | **Required.** A dictionary containing information which days and durations apply to this timeperiod.
-  child\_options            | String                | **Optional.** Schedule child downtimes. `DowntimeNoChildren` does not do anything, `DowntimeTriggeredChildren` schedules child downtimes triggered by this downtime, `DowntimeTriggeredChildren` schedules non-triggered downtimes. Defaults to `DowntimeNoChildren`.
+  child\_options            | String                | **Optional.** Schedule child downtimes. `DowntimeNoChildren` does not do anything, `DowntimeTriggeredChildren` schedules child downtimes triggered by this downtime, `DowntimeNonTriggeredChildren` schedules non-triggered downtimes. Defaults to `DowntimeNoChildren`.
 
 ScheduledDowntime objects have composite names, i.e. their names are based
 on the `host_name` and `service_name` attributes and the
diff --git a/doc/12-icinga2-api.md b/doc/12-icinga2-api.md
index 50b107c88..c26ef937d 100644
--- a/doc/12-icinga2-api.md
+++ b/doc/12-icinga2-api.md
@@ -1117,7 +1117,7 @@ Send a `POST` request to the URL endpoint `/v1/actions/schedule-downtime`.
   fixed         | Boolean   | **Optional.** Defaults to `true`. If true, the downtime is `fixed` otherwise `flexible`. See [downtimes](08-advanced-topics.md#downtimes) for more information.
   duration      | Number    | **Required for flexible downtimes.** Duration of the downtime in seconds if `fixed` is set to false.
   trigger\_name | String    | **Optional.** Sets the trigger for a triggered downtime. See [downtimes](08-advanced-topics.md#downtimes) for more information on triggered downtimes.
-  child\_options| String    | **Optional.** Schedule child downtimes. `DowntimeNoChildren` does not do anything, `DowntimeTriggeredChildren` schedules child downtimes triggered by this downtime, `DowntimeTriggeredChildren` schedules non-triggered downtimes. Defaults to `DowntimeNoChildren`.
+  child\_options| String    | **Optional.** Schedule child downtimes. `DowntimeNoChildren` does not do anything, `DowntimeTriggeredChildren` schedules child downtimes triggered by this downtime, `DowntimeNonTriggeredChildren` schedules non-triggered downtimes. Defaults to `DowntimeNoChildren`.
 
 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`.
 
diff --git a/doc/16-upgrading-icinga-2.md b/doc/16-upgrading-icinga-2.md
index ab5bd649b..f483ff0e3 100644
--- a/doc/16-upgrading-icinga-2.md
+++ b/doc/16-upgrading-icinga-2.md
@@ -49,6 +49,11 @@ New [Icinga constants](17-language-reference.md#icinga-constants) have been adde
 The keywords `namespace` and `using` are now [reserved](17-language-reference.md#reserved-keywords) for the namespace functionality provided
 with v2.10. Read more about how it works [here](17-language-reference.md#namespaces).
 
+### API: schedule-downtime Action <a id="upgrading-to-2-10-api-schedule-downtime-action"></a>
+
+The attribute `child_options` was previously accepting 0,1,2 for specific child downtime settings.
+This behaviour stays intact, but the new proposed way are specific constants as values (`DowntimeNoChildren`, `DowntimeTriggeredChildren`, `DowntimeNonTriggeredChildren`).
+
 ## Upgrading to v2.9 <a id="upgrading-to-2-9"></a>
 
 ### Deprecation and Removal Notes <a id="upgrading-to-2-9-deprecation-removal-notes"></a>