diff --git a/docs/reference/ml/apis/put-datafeed.asciidoc b/docs/reference/ml/apis/put-datafeed.asciidoc
index 18c611e97cac1..05e02ce3615df 100644
--- a/docs/reference/ml/apis/put-datafeed.asciidoc
+++ b/docs/reference/ml/apis/put-datafeed.asciidoc
@@ -19,6 +19,11 @@ Instantiates a {dfeed}.
 You must create a job before you create a {dfeed}.  You can associate only one
 {dfeed} to each job.
 
+IMPORTANT:  You must use {kib} or this API to create a {dfeed}. Do not put a {dfeed}
+            directly to the `.ml-config` index using the Elasticsearch index API.
+            If {es} {security-features} are enabled, do not give users `write`
+            privileges on the `.ml-config` index.
+
 
 ==== Path Parameters
 
diff --git a/docs/reference/ml/apis/put-job.asciidoc b/docs/reference/ml/apis/put-job.asciidoc
index 4abeebee3e47a..e3d80c276dc55 100644
--- a/docs/reference/ml/apis/put-job.asciidoc
+++ b/docs/reference/ml/apis/put-job.asciidoc
@@ -12,7 +12,13 @@ Instantiates a job.
 
 `PUT _ml/anomaly_detectors/<job_id>`
 
-//===== Description
+===== Description
+
+IMPORTANT: You must use {kib} or this API to create a {ml} job. Do not put a job
+            directly to the `.ml-config` index using the Elasticsearch index API.
+            If {es} {security-features} are enabled, do not give users `write`
+            privileges on the `.ml-config` index.
+
 
 ==== Path Parameters