[DOCS] Add machine learning sync API (#112033) (#112687)

docs/api/machine-learning.asciidoc

@@ -0,0 +1,11 @@
+[[machine-learning-api]]
+== {ml-cap} APIs
+
+//Manage {kib} saved objects, including dashboards, visualizations, and more.
+
+The following {ml} API is available: 
+
+* <<machine-learning-api-sync, Sync API>>
+//to retrieve a single {kib} saved object by ID
+
+include::machine-learning/sync.asciidoc[]

docs/api/machine-learning/sync.asciidoc

@@ -0,0 +1,79 @@
+[[machine-learning-api-sync]]
+=== Sync {ml} saved objects API
+++++
+<titleabbrev>Sync {ml} saved objects</titleabbrev>
+++++
+
+Synchronizes {kib} saved objects for {ml} jobs.
+
+[[machine-learning-api-sync-request]]
+==== Request
+
+`GET <kibana host>:<port>/api/ml/saved_objects/sync`
+
+`GET <kibana host>:<port>/s/<space_id>/api/ml/saved_objects/sync`
+
+
+[[machine-learning-api-sync-path-params]]
+==== Path parameters
+
+`space_id`::
+(Optional, string) An identifier for the space. If `space_id` is not provided in
+the URL the default space is used.
+
+[[machine-learning-api-sync-query-params]]
+==== Query parameters
+
+`simulate`::
+(Optional, boolean) When `true`, simulates the synchronization by only returning
+the list actions that _would_ be performed.
+
+[[machine-learning-api-sync-response-body]]
+==== Response body
+
+`datafeedsAdded`::
+(array) If a saved object for an {anomaly-job} is missing a {dfeed} identifier,
+it is added. This list contains the {dfeed} identifiers and indicates whether
+the synchronization was successful.
+
+`datafeedsRemoved`::
+(array) If saved objects exist for {dfeeds} that no longer exist, they are
+deleted. This list contains the {dfeed} identifiers and indicates whether the
+synchronization was successful.
+
+`savedObjectsCreated`::
+(array) If saved objects are missing for {ml} jobs, they are created. This
+list contains the job identifiers and indicates whether the synchronization was
+successful.
+
+`savedObjectsDeleted`::
+(array) If saved objects exist for jobs that no longer exist, they are deleted. 
+This list contains the job identifiers and indicates whether the synchronization
+was successful.
+
+[[machine-learning-api-sync-codes]]
+==== Response code
+
+`200`::
+  Indicates a successful call.
+
+[[machine-learning-api-sync-example]]
+==== Example
+
+Retrieve the list of {ml} saved objects that require synchronization:
+
+[source,sh]
+--------------------------------------------------
+$ curl -X GET api/ml/saved_objects/sync?simulate=true
+--------------------------------------------------
+// KIBANA
+
+If there are two jobs and a {dfeed} that need to be synchronized, for example,
+the API returns the following:
+
+[source,sh]
+--------------------------------------------------
+{{"savedObjectsCreated":{"myjob1":{"success":true},"myjob2":{"success":true}},"savedObjectsDeleted":{},"datafeedsAdded":{},"datafeedsRemoved":{"myfeed3":{"success":true}}}
+--------------------------------------------------
+
+To perform the synchronization, re-run the API and omit the `simulate` parameter.

docs/user/api.asciidoc

@@ -96,6 +96,7 @@ include::{kib-repo-dir}/api/alerting.asciidoc[]
 include::{kib-repo-dir}/api/actions-and-connectors.asciidoc[]
 include::{kib-repo-dir}/api/dashboard-api.asciidoc[]
 include::{kib-repo-dir}/api/logstash-configuration-management.asciidoc[]
+include::{kib-repo-dir}/api/machine-learning.asciidoc[]
 include::{kib-repo-dir}/api/url-shortening.asciidoc[]
 include::{kib-repo-dir}/api/task-manager/health.asciidoc[]
 include::{kib-repo-dir}/api/upgrade-assistant.asciidoc[]