diff --git a/docs/reference/ml/df-analytics/apis/index.asciidoc b/docs/reference/ml/df-analytics/apis/index.asciidoc
index 8c0f8713c90ab..5e7a0791775f4 100644
--- a/docs/reference/ml/df-analytics/apis/index.asciidoc
+++ b/docs/reference/ml/df-analytics/apis/index.asciidoc
@@ -18,8 +18,12 @@ include::get-dfanalytics.asciidoc[leveloffset=+2]
include::get-dfanalytics-stats.asciidoc[leveloffset=+2]
include::get-trained-models.asciidoc[leveloffset=+2]
include::get-trained-models-stats.asciidoc[leveloffset=+2]
+//INFER
+include::infer-trained-model-deployment.asciidoc[leveloffset=+2]
//PREVIEW
include::preview-dfanalytics.asciidoc[leveloffset=+2]
//SET/START/STOP
include::start-dfanalytics.asciidoc[leveloffset=+2]
+include::start-trained-model-deployment.asciidoc[leveloffset=+2]
include::stop-dfanalytics.asciidoc[leveloffset=+2]
+include::stop-trained-model-deployment.asciidoc[leveloffset=+2]
diff --git a/docs/reference/ml/df-analytics/apis/infer-trained-model-deployment.asciidoc b/docs/reference/ml/df-analytics/apis/infer-trained-model-deployment.asciidoc
new file mode 100644
index 0000000000000..9e1ce728d553d
--- /dev/null
+++ b/docs/reference/ml/df-analytics/apis/infer-trained-model-deployment.asciidoc
@@ -0,0 +1,116 @@
+[role="xpack"]
+[testenv="basic"]
+[[infer-trained-model-deployment]]
+= Infer trained model deployment API
+[subs="attributes"]
+++++
+Infer trained model deployment
+++++
+
+Evaluates a trained model.
+
+[[infer-trained-model-deployment-request]]
+== {api-request-title}
+
+`POST _ml/trained_models//deployment/_infer`
+
+////
+[[infer-trained-model-deployment-prereq]]
+== {api-prereq-title}
+
+////
+////
+[[infer-trained-model-deployment-desc]]
+== {api-description-title}
+
+////
+
+[[infer-trained-model-deployment-path-params]]
+== {api-path-parms-title}
+
+``::
+(Required, string)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id]
+
+[[infer-trained-model-deployment-query-params]]
+== {api-query-parms-title}
+
+`timeout`::
+(Optional, time)
+Controls the amount of time to wait for {infer} results. Defaults to 10 seconds.
+
+[[infer-trained-model-request-body]]
+== {api-request-body-title}
+
+`input`::
+(Required,string)
+The input text for evaluation.
+
+////
+[[infer-trained-model-deployment-results]]
+== {api-response-body-title}
+////
+////
+[[ml-get-trained-models-response-codes]]
+== {api-response-codes-title}
+
+////
+
+[[infer-trained-model-deployment-example]]
+== {api-examples-title}
+
+The response depends on the task the model is trained for. If it is a
+sentiment analysis task, the response is the score. For example:
+
+[source,console]
+--------------------------------------------------
+POST _ml/trained_models/model2/deployment/_infer
+{
+ "input": "The movie was awesome!!"
+}
+--------------------------------------------------
+// TEST[skip:TBD]
+
+The API returns scores in this case, for example:
+
+[source,console-result]
+----
+{
+ "positive" : 0.9998062667902223,
+ "negative" : 1.9373320977752957E-4
+}
+----
+// NOTCONSOLE
+
+For named entity recognition (NER) tasks, the response contains the recognized
+entities and their type. For example:
+
+[source,console]
+--------------------------------------------------
+POST _ml/trained_models/model2/deployment/_infer
+{
+ "input": "Hi my name is Josh and I live in Berlin"
+}
+--------------------------------------------------
+// TEST[skip:TBD]
+
+The API returns scores in this case, for example:
+
+[source,console-result]
+----
+{
+ "entities" : [
+ {
+ "label" : "person",
+ "score" : 0.9988716330253505,
+ "word" : "Josh"
+ },
+ {
+ "label" : "location",
+ "score" : 0.9980872542990656,
+ "word" : "Berlin"
+ }
+ ]
+}
+----
+// NOTCONSOLE
diff --git a/docs/reference/ml/df-analytics/apis/ml-df-analytics-apis.asciidoc b/docs/reference/ml/df-analytics/apis/ml-df-analytics-apis.asciidoc
index f2fc3f35016e7..e23533b959373 100644
--- a/docs/reference/ml/df-analytics/apis/ml-df-analytics-apis.asciidoc
+++ b/docs/reference/ml/df-analytics/apis/ml-df-analytics-apis.asciidoc
@@ -3,34 +3,36 @@
[[ml-df-analytics-apis]]
= {ml-cap} {dfanalytics} APIs
-You can use the following APIs to perform {ml} {dfanalytics} activities.
+You can use the following APIs to perform {ml} {dfanalytics} activities:
-* <>
* <>
-* <>
* <>
* <>
* <>
-* <>
-* <>
* <>
* <>
+* <>
+* <>
+* <>
+* <>
-
-You can use the following APIs to perform {infer} operations.
+You can use the following APIs to perform {infer} operations:
* <>
-* <>
-* <>
-* <>
* <>
+* <>
* <>
+* <>
+* <>
You can deploy a trained model to make predictions in an ingest pipeline or in
-an aggregation. Refer to the following documentation to learn more.
+an aggregation. Refer to the following documentation to learn more:
-* <>
* <>
+* <>
+* <>
+* <>
+* <>
See also <>.
diff --git a/docs/reference/ml/df-analytics/apis/start-trained-model-deployment.asciidoc b/docs/reference/ml/df-analytics/apis/start-trained-model-deployment.asciidoc
new file mode 100644
index 0000000000000..957cbc09f1ec1
--- /dev/null
+++ b/docs/reference/ml/df-analytics/apis/start-trained-model-deployment.asciidoc
@@ -0,0 +1,54 @@
+[role="xpack"]
+[testenv="basic"]
+[[start-trained-model-deployment]]
+= Start trained model deployment API
+[subs="attributes"]
+++++
+Start trained model deployment
+++++
+
+[[start-trained-model-deployment-request]]
+== {api-request-title}
+
+`POST _ml/trained_models//deployent/_start`
+////
+[[start-trained-model-deployment-prereq]]
+== {api-prereq-title}
+
+////
+////
+[[start-trained-model-deployment-desc]]
+== {api-description-title}
+
+////
+
+[[start-trained-model-deployment-path-params]]
+== {api-path-parms-title}
+
+``::
+(Required, string)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id]
+
+[[start-trained-model-deployment-query-params]]
+== {api-query-parms-title}
+
+`timeout`::
+(Optional, time)
+Controls the amount of time to wait for the model to deploy. Defaults
+to 20 seconds.
+////
+[role="child_attributes"]
+[[start-trained-model-deployment-results]]
+== {api-response-body-title}
+
+////
+////
+[[ml-get-trained-models-response-codes]]
+== {api-response-codes-title}
+
+////
+////
+[[start-trained-model-deployment-example]]
+== {api-examples-title}
+
+////
\ No newline at end of file
diff --git a/docs/reference/ml/df-analytics/apis/stop-trained-model-deployment.asciidoc b/docs/reference/ml/df-analytics/apis/stop-trained-model-deployment.asciidoc
new file mode 100644
index 0000000000000..6302fa8257697
--- /dev/null
+++ b/docs/reference/ml/df-analytics/apis/stop-trained-model-deployment.asciidoc
@@ -0,0 +1,49 @@
+[role="xpack"]
+[testenv="basic"]
+[[stop-trained-model-deployment]]
+= Stop trained model deployment API
+[subs="attributes"]
+++++
+Stop trained model deployment
+++++
+
+[[stop-trained-model-deployment-request]]
+== {api-request-title}
+
+`POST _ml/trained_models//deployment/_stop`
+
+////
+[[stop-trained-model-deployment-prereq]]
+== {api-prereq-title}
+
+////
+////
+[[stop-trained-model-deployment-desc]]
+== {api-description-title}
+
+////
+[[stop-trained-model-deployment-path-params]]
+== {api-path-parms-title}
+
+``::
+(Required, string)
+include::{es-repo-dir}/ml/ml-shared.asciidoc[tag=model-id]
+
+////
+[[stop-trained-model-deployment-query-params]]
+== {api-query-parms-title}
+////
+////
+[role="child_attributes"]
+[[stop-trained-model-deployment-results]]
+== {api-response-body-title}
+////
+////
+[[ml-get-trained-models-response-codes]]
+== {api-response-codes-title}
+////
+
+////
+[[stop-trained-model-deployment-example]]
+== {api-examples-title}
+////
\ No newline at end of file
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.infer_trained_model_deployment.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.infer_trained_model_deployment.json
index cc47b53691601..8b242a34b3e16 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.infer_trained_model_deployment.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.infer_trained_model_deployment.json
@@ -1,7 +1,7 @@
{
"ml.infer_trained_model_deployment":{
"documentation":{
- "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-df-analytics-apis.html",
+ "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/infer-trained-model-deployment.html",
"description":"Evaluate a trained model."
},
"stability":"experimental",
@@ -20,7 +20,8 @@
"parts":{
"model_id":{
"type":"string",
- "description":"The ID of the model to perform inference on"
+ "description":"The unique identifier of the trained model.",
+ "required":true
}
}
}
@@ -30,8 +31,13 @@
"timeout":{
"type":"time",
"required":false,
- "description":"Controls the time to wait for the inference result"
+ "description":"Controls the amount of time to wait for inference results.",
+ "default":"10s"
}
+ },
+ "body":{
+ "description":"The input text to be evaluated.",
+ "required":true
}
}
}
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.start_trained_model_deployment.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.start_trained_model_deployment.json
index f14ea92d475e8..1067c09f3b709 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.start_trained_model_deployment.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.start_trained_model_deployment.json
@@ -1,7 +1,7 @@
{
"ml.start_trained_model_deployment":{
"documentation":{
- "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-df-analytics-apis.html",
+ "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/start-trained-model-deployment.html",
"description":"Start a trained model deployment."
},
"stability":"experimental",
@@ -20,7 +20,8 @@
"parts":{
"model_id":{
"type":"string",
- "description":"The ID of the model to deploy"
+ "description":"The unique identifier of the trained model.",
+ "required":true
}
}
}
@@ -30,7 +31,8 @@
"timeout":{
"type":"time",
"required":false,
- "description":"Controls the time to wait until the model is deployed"
+ "description":"Controls the amount of time to wait for the model to deploy.",
+ "default": "20s"
}
}
}
diff --git a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.stop_trained_model_deployment.json b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.stop_trained_model_deployment.json
index 0c46615d9bf6d..3e608a890b0a1 100644
--- a/rest-api-spec/src/main/resources/rest-api-spec/api/ml.stop_trained_model_deployment.json
+++ b/rest-api-spec/src/main/resources/rest-api-spec/api/ml.stop_trained_model_deployment.json
@@ -1,7 +1,7 @@
{
"ml.stop_trained_model_deployment":{
"documentation":{
- "url":"https://www.elastic.co/guide/en/elasticsearch/reference/current/ml-df-analytics-apis.html",
+ "url":"https://www.elastic.co/guide/en/elasticsearch/reference/master/stop-trained-model-deployment.html",
"description":"Stop a trained model deployment."
},
"stability":"experimental",
@@ -20,7 +20,8 @@
"parts":{
"model_id":{
"type":"string",
- "description":"The ID of the model to undeploy"
+ "description":"The unique identifier of the trained model.",
+ "required":true
}
}
}