[DOCS] Adds reference documentation for inference API (elastic#99658)

* [DOCS] Creates documentation structure.

* [DOCS] Adds PUT inference API docs and part of GET inference API docs.

* [DOCS] Fixes complaining CI.

* [DOCS] Adds GET and DELETE API docs for inference API.

* [DOCS] Adds POST inference API docs.

* Apply suggestions from code review

docs/reference/inference/delete-inference.asciidoc

@@ -0,0 +1,57 @@
+[role="xpack"]
+[[delete-inference-api]]
+=== Delete {infer} API
+
+Deletes an {infer} model deployment.
+
+
+[discrete]
+[[delete-inference-api-request]]
+==== {api-request-title}
+
+`DELETE /_inference/<task_type>/<model_id>`
+
+[discrete]
+[[delete-inference-api-prereqs]]
+==== {api-prereq-title}
+
+* Requires the `manage` <<privileges-list-cluster,cluster privilege>>.
+
+
+[discrete]
+[[delete-inference-api-path-params]]
+==== {api-path-parms-title}
+
+<model_id>::
+(Required, string)
+The unique identifier of the {infer} model to delete.
+
+<task_type>::
+(Required, string)
+The type of {infer} task that the model performs.
+
+
+[discrete]
+[[delete-inference-api-example]]
+==== {api-examples-title}
+
+The following API call deletes the `my-elser-model` {infer} model that can 
+perform `sparse_embedding` tasks.
+
+
+[source,console]
+------------------------------------------------------------
+DELETE /_inference/sparse_embedding/my-elser-model
+------------------------------------------------------------
+// TEST[skip:TBD]
+
+
+The API returns the following response:
+
+[source,console-result]
+------------------------------------------------------------
+{
+  "acknowledged": true
+}
+------------------------------------------------------------
+// NOTCONSOLE

docs/reference/inference/get-inference.asciidoc

@@ -0,0 +1,79 @@
+[role="xpack"]
+[[get-inference-api]]
+=== Get {infer} API
+
+Retrieves {infer} model information.
+
+[discrete]
+[[get-inference-api-request]]
+==== {api-request-title}
+
+`GET /_inference/_all`
+
+`GET /_inference/<task_type>/_all`
+
+`GET /_inference/<task_type>/<model_id>`
+
+[discrete]
+[[get-inference-api-prereqs]]
+==== {api-prereq-title}
+
+* Requires the `manage` <<privileges-list-cluster,cluster privilege>>.
+
+[discrete]
+[[get-inference-api-desc]]
+==== {api-description-title}
+
+You can get information in a single API request for: 
+
+* a single {infer} model by providing the task type and the model ID,
+* all of the {infer} models for a certain task type by providing the task type 
+and a wildcard expression,
+* all of the {infer} models by using a wildcard expression.
+
+
+[discrete]
+[[get-inference-api-path-params]]
+==== {api-path-parms-title}
+
+`<model_id>`::
+(Optional, string)
+The unique identifier of the {infer} model.
+
+
+`<task_type>`::
+(Optional, string)
+The type of {infer} task that the model performs.
+
+
+[discrete]
+[[get-inference-api-example]]
+==== {api-examples-title}
+
+The following API call retrives information about the `my-elser-model` {infer} 
+model that can perform `sparse_embedding` tasks.
+
+
+[source,console]
+------------------------------------------------------------
+GET _inference/sparse_embedding/my-elser-model
+------------------------------------------------------------
+// TEST[skip:TBD]
+
+
+The API returns the following response:
+
+[source,console-result]
+------------------------------------------------------------
+{
+  "model_id": "my-elser-model",
+  "task_type": "sparse_embedding",
+  "service": "elser_mlnode",
+  "service_settings": {
+    "num_allocations": 1,
+    "num_threads": 1
+  },
+  "task_settings": {}
+}
+------------------------------------------------------------
+// NOTCONSOLE

docs/reference/inference/inference-apis.asciidoc

@@ -0,0 +1,16 @@
+[role="xpack"]
+[[inference-apis]]
+== {infer-cap} APIs
+
+You can use the following APIs to manage {infer} models and perform {infer}:
+
+* <<delete-inference-api>>
+* <<get-inference-api>>
+* <<post-inference-api>>
+* <<put-inference-api>>
+
+
+include::delete-inference.asciidoc[]
+include::get-inference.asciidoc[]
+include::post-inference.asciidoc[]
+include::put-inference.asciidoc[]

docs/reference/inference/post-inference.asciidoc

@@ -0,0 +1,97 @@
+[role="xpack"]
+[[post-inference-api]]
+=== Perform inference API
+
+Performs an inference task on an input text by using an {infer} model.
+
+
+[discrete]
+[[post-inference-api-request]]
+==== {api-request-title}
+
+`POST /_inference/<task_type>/<model_id>`
+
+
+[discrete]
+[[post-inference-api-prereqs]]
+==== {api-prereq-title}
+
+* Requires the `manage` <<privileges-list-cluster,cluster privilege>>.
+
+
+[discrete]
+[[post-inference-api-desc]]
+==== {api-description-title}
+
+The perform {infer} API enables you to use {infer} models to perform specific 
+tasks on data that you provide as an input. The API returns a response with the 
+resutls of the tasks. The {infer} model you use can perform one specific task 
+that has been defined when the model was created with the <<put-inference-api>>.
+
+
+[discrete]
+[[post-inference-api-path-params]]
+==== {api-path-parms-title}
+
+`<model_id>`::
+(Required, string)
+The unique identifier of the {infer} model.
+
+
+`<task_type>`::
+(Required, string)
+The type of {infer} task that the model performs.
+
+
+[discrete]
+[[post-inference-api-request-body]]
+== {api-request-body-title}
+
+`input`::
+(Required, string)
+The text on which you want to perform the {infer} task.
+
+
+[discrete]
+[[post-inference-api-example]]
+==== {api-examples-title}
+
+The following example performs sparse embedding on the example sentence.
+
+
+[source,console]
+------------------------------------------------------------
+POST _inference/sparse_embedding/my-elser-model
+{
+  "input": "The sky above the port was the color of television tuned to a dead channel."
+}
+------------------------------------------------------------
+// TEST[skip:TBD]
+
+
+The API returns the following response:
+
+
+[source,console-result]
+------------------------------------------------------------
+{
+  "sparse_embedding": {
+    "port": 2.1259406,
+    "sky": 1.7073475,
+    "color": 1.6922266,
+    "dead": 1.6247464,
+    "television": 1.3525393,
+    "above": 1.2425821,
+    "tuned": 1.1440028,
+    "colors": 1.1218185,
+    "tv": 1.0111054,
+    "ports": 1.0067928,
+    "poem": 1.0042328,
+    "channel": 0.99471164,
+    "tune": 0.96235967,
+    "scene": 0.9020516,
+    (...)
+  }
+}
+------------------------------------------------------------
+// NOTCONSOLE

docs/reference/inference/put-inference.asciidoc

@@ -0,0 +1,104 @@
+[role="xpack"]
+[[put-inference-api]]
+=== Create {infer} API
+
+Creates a model to perform an {infer} task.
+
+
+[discrete]
+[[put-inference-api-request]]
+==== {api-request-title}
+
+`PUT /_inference/<task_type>/<model_id>`
+
+
+[discrete]
+[[put-inference-api-prereqs]]
+==== {api-prereq-title}
+
+* Requires the `manage` <<privileges-list-cluster,cluster privilege>>.
+
+[discrete]
+[[put-inference-api-desc]]
+==== {api-description-title}
+
+The create {infer} API enables you to create and configure an {infer} model to 
+perform a specific {infer} task. 
+
+
+[discrete]
+[[put-inference-api-path-params]]
+==== {api-path-parms-title}
+
+
+`<model_id>`::
+(Required, string)
+The unique identifier of the model.
+
+`<task_type>`::
+(Required, string)
+The type of the {infer} task that the model will perform. Available task types:
+* `sparse_embedding`,
+* `text_embedding`.
+
+
+[discrete]
+[[put-inference-api-request-body]]
+== {api-request-body-title}
+
+`service`::
+(Required, string)
+The type of service supported for the specified task type.
+Available services:
+* `elser`,
+* `elser_mlnode`.
+
+`service_settings`::
+(Required, object)
+Settings used to install the {infer} model. These settings are specific to the 
+`service` you specified.
+
+`task_settings`::
+(Optional, object)
+Settings to configure the {infer} task. These settings are specific to the 
+`<task_type>` you specified.
+
+
+[discrete]
+[[put-inference-api-example]]
+==== {api-examples-title}
+
+The following example shows how to create an {infer} model called 
+`my-elser-model` to perform a `sparse_embedding` task type.
+
+[source,console]
+------------------------------------------------------------
+PUT _inference/sparse_embedding/my-elser-model
+{
+  "service": "elser_mlnode",
+  "service_settings": {
+    "num_allocations": 1,
+    "num_threads": 1
+  },
+  "task_settings": {}
+}
+------------------------------------------------------------
+// TEST[skip:TBD]
+
+
+Example response:
+
+[source,console-result]
+------------------------------------------------------------
+{
+  "model_id": "my-elser-model",
+  "task_type": "sparse_embedding",
+  "service": "elser_mlnode",
+  "service_settings": {
+    "num_allocations": 1,
+    "num_threads": 1
+  },
+  "task_settings": {}
+}
+------------------------------------------------------------
+// NOTCONSOLE

docs/reference/rest-api/index.asciidoc

@@ -28,8 +28,9 @@ not be included yet.
 * <<graph-explore-api,Graph explore API>>
 * <<indices, Index APIs>>
 * <<index-lifecycle-management-api,Index lifecycle management APIs>>
-* <<ingest-apis,Ingest APIs>>
+* <<inference-apis,Inference APIs>>
 * <<info-api,Info API>>
+* <<ingest-apis,Ingest APIs>>
 * <<licensing-apis,Licensing APIs>>
 * <<logstash-apis,Logstash APIs>>
 * <<ml-apis,{ml-cap} APIs>>
@@ -74,8 +75,9 @@ include::{es-repo-dir}/text-structure/apis/find-structure.asciidoc[leveloffset=+
 include::{es-repo-dir}/graph/explore.asciidoc[]
 include::{es-repo-dir}/indices.asciidoc[]
 include::{es-repo-dir}/ilm/apis/ilm-api.asciidoc[]
-include::{es-repo-dir}/ingest/apis/index.asciidoc[]
+include::{es-repo-dir}/inference/inference-apis.asciidoc[]
 include::info.asciidoc[]
+include::{es-repo-dir}/ingest/apis/index.asciidoc[]
 include::{es-repo-dir}/licensing/index.asciidoc[]
 include::{es-repo-dir}/rest-api/logstash/index.asciidoc[]
 include::{es-repo-dir}/ml/common/apis/index.asciidoc[]