diff --git a/docs/reference/ml/apis/update-job.asciidoc b/docs/reference/ml/apis/update-job.asciidoc
index c9a596cec28ca..d601f68779cc5 100644
--- a/docs/reference/ml/apis/update-job.asciidoc
+++ b/docs/reference/ml/apis/update-job.asciidoc
@@ -8,17 +8,19 @@
 
 Updates certain properties of a job.
 
-==== Request
+[[ml-update-job-request]]
+==== {api-request-title}
 
 `POST _xpack/ml/anomaly_detectors/<job_id>/_update`
 
-
-==== Path Parameters
+[[ml-update-job-path-parms]]
+==== {api-path-parms-title}
 
 `job_id` (required)::
   (string) Identifier for the job
 
-==== Request Body
+[[ml-update-job-request-body]]
+==== {api-request-body-title}
 
 The following properties can be updated after the job is created:
 
@@ -26,8 +28,11 @@ The following properties can be updated after the job is created:
 |=======================================================================
 |Name |Description |Requires Restart
 
-|`analysis_limits`: `model_memory_limit` |The approximate maximum amount of
-memory resources required for analytical processing. See <<ml-apilimits>>. | Yes
+|`analysis_limits`: `model_memory_limit` |The approximate maximum amount of 
+memory resources required for analytical processing. See <<ml-apilimits>>. You 
+can update the `analysis_limits` only while the job is closed. The 
+`model_memory_limit` property value cannot be decreased below the current usage. 
+| Yes
 
 |`background_persist_interval` |Advanced configuration option. The time between
 each periodic persistence of the model. See <<ml-job-resource>>. | Yes
@@ -36,11 +41,18 @@ each periodic persistence of the model. See <<ml-job-resource>>. | Yes
 
 |`description` |A description of the job. See <<ml-job-resource>>. | No
 
-|`detectors` |An array of <<ml-detector-update, detector update objects>>. | No
+|`detectors` |An array of detector update objects. | No
+
+|`detector_index` |The identifier of the detector to update (integer).| No
+
+|`detectors.description` |The new description for the detector.| No
+
+|`detectors.custom_rules` |The new list of <<ml-detector-custom-rule, rules>> 
+for the detector. | No
 
 |`groups` |A list of job groups. See <<ml-job-resource>>. | No
 
-|`model_plot_config`: `enabled` |If true, enables calculation and storage of the
+|`model_plot_config.enabled` |If true, enables calculation and storage of the
 model bounds for each entity that is being analyzed.
 See <<ml-apimodelplotconfig>>. | No
 
@@ -63,37 +75,20 @@ effect.
 
 [NOTE]
 --
-* You can update the `analysis_limits` only while the job is closed.
-* The `model_memory_limit` property value cannot be decreased below the current usage.
 * If the `memory_status` property in the `model_size_stats` object has a value
 of `hard_limit`, this means that it was unable to process some data. You might
 want to re-run this job with an increased `model_memory_limit`.
 --
 
-[[ml-detector-update]]
-==== Detector Update Objects
-
-A detector update object has the following properties:
-
-`detector_index`::
-  (integer) The identifier of the detector to update.
-
-`description`::
-  (string) The new description for the detector.
-
-`custom_rules`::
-  (array) The new list of <<ml-detector-custom-rule, rules>> for the detector.
-
-No other detector property can be updated.
-
-==== Authorization
+[[ml-update-job-prereqs]]
+==== {api-prereq-title}
 
 You must have `manage_ml`, or `manage` cluster privileges to use this API.
 For more information, see
-{xpack-ref}/security-privileges.html[Security Privileges].
-
+{xpack-ref}/security-privileges.html[Security privileges].
 
-==== Examples
+[[ml-update-job-example]]
+==== {api-examples-title}
 
 The following example updates the `total-requests` job: