[role="xpack"]
[[put-trained-models-aliases]]
= Create or update trained model aliases API
[subs="attributes"]
++++
<titleabbrev>Create or update trained model aliases</titleabbrev>
++++

.New API reference
[sidebar]
--
For the most up-to-date API details, refer to {api-es}/group/endpoint-ml-trained-model[{ml-cap} trained model APIs].
--

Creates or updates a trained model alias.

A trained model alias is a logical name used to reference a single trained model.

[[ml-put-trained-models-aliases-request]]
== {api-request-title}

`PUT _ml/trained_models/<model_id>/model_aliases/<model_alias>`


[[ml-put-trained-models-aliases-prereq]]
== {api-prereq-title}

Requires the `manage_ml` cluster privilege. This privilege is included in the
`machine_learning_admin` built-in role.


[[ml-put-trained-models-aliases-desc]]
== {api-description-title}

You can use aliases instead of trained model identifiers to make it easier to
reference your models. For example, you can use aliases in {infer} aggregations
and processors.

An alias must be unique and refer to only a single trained model. However,
you can have multiple aliases for each trained model.

API Restrictions:

* You are not allowed to update an alias such that it references a different
trained model ID and the model uses a different type of {dfanalytics}. For example,
this situation occurs if you have a trained model for
{reganalysis} and a trained model for {classanalysis}; you cannot reassign an
alias from one type of trained model to another.
* You cannot update an alias from a `pytorch` model and a {dfanalytics} model.
* You cannot update the alias from a deployed `pytorch` model to one
not currently deployed.

If you use this API to update an alias and there are very few input fields in
common between the old and new trained models for the model alias, the API
returns a warning.

[[ml-put-trained-models-aliases-path-params]]
== {api-path-parms-title}

`model_alias`::
(Required, string)
The alias to create or update. This value cannot end in numbers.

`model_id`::
(Required, string)
The identifier for the trained model that the alias refers to.

[[ml-put-trained-models-aliases-query-params]]
== {api-query-parms-title}

`reassign`::
(Optional, boolean)
Specifies whether the alias gets reassigned to the specified trained model if it
is already assigned to a different model. If the alias is already assigned and
this parameter is `false`, the API returns an error. Defaults to `false`.

[[ml-put-trained-models-aliases-example]]
== {api-examples-title}

[[ml-put-trained-models-aliases-example-new-alias]]
=== Create a trained model alias

The following example shows how to create an alias (`flight_delay_model`) for a
trained model (`flight-delay-prediction-1574775339910`):

[source,console]
--------------------------------------------------
PUT _ml/trained_models/flight-delay-prediction-1574775339910/model_aliases/flight_delay_model
--------------------------------------------------
// TEST[skip:setup kibana sample data]

[[ml-put-trained-models-aliases-example-put-alias]]
=== Update a trained model alias

The following example shows how to reassign an alias (`flight_delay_model`) to a
different trained model (`flight-delay-prediction-1580004349800`):

[source,console]
--------------------------------------------------
PUT _ml/trained_models/flight-delay-prediction-1580004349800/model_aliases/flight_delay_model?reassign=true
--------------------------------------------------
// TEST[skip:setup kibana sample data]