From 94b4239a85f6b305724fdd1488666d8544c0f750 Mon Sep 17 00:00:00 2001
From: Lisa Cawley <lcawley@elastic.co>
Date: Tue, 21 Sep 2021 08:44:34 -0700
Subject: [PATCH] [DOCS] Add machine learning sync API (#112033) (#112687)

---
 docs/api/machine-learning.asciidoc      | 11 ++++
 docs/api/machine-learning/sync.asciidoc | 79 +++++++++++++++++++++++++
 docs/user/api.asciidoc                  |  1 +
 3 files changed, 91 insertions(+)
 create mode 100644 docs/api/machine-learning.asciidoc
 create mode 100644 docs/api/machine-learning/sync.asciidoc

diff --git a/docs/api/machine-learning.asciidoc b/docs/api/machine-learning.asciidoc
new file mode 100644
index 000000000000..265896e6340d
--- /dev/null
+++ b/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[]
diff --git a/docs/api/machine-learning/sync.asciidoc b/docs/api/machine-learning/sync.asciidoc
new file mode 100644
index 000000000000..5f19bc17ab2f
--- /dev/null
+++ b/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.
\ No newline at end of file
diff --git a/docs/user/api.asciidoc b/docs/user/api.asciidoc
index 00aa3c545df6..12e200bb0ba2 100644
--- a/docs/user/api.asciidoc
+++ b/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[]