Elastic Stack (ELK Stack) ml trained model API

openapi: 3.2.0
info:
  title: Elasticsearch Request & Response Specification ml trained model API
  license:
    name: Apache 2.0
    url: https://github.com/elastic/elasticsearch-specification/blob/main/LICENSE
  version: ''
tags:
- name: ml trained model
paths:
  /_ml/trained_models/{model_id}/deployment/cache/_clear:
    post:
      tags:
      - ml trained model
      summary: Clear trained model deployment cache
      description: 'Cache will be cleared on all nodes where the trained model is assigned.

        A trained model deployment may have an inference cache enabled.

        As requests are handled by each allocated node, their responses may be cached on that individual node.

        Calling this API clears the caches without restarting the deployment.


        ## Required authorization


        * Cluster privileges: `manage_ml`

        '
      operationId: ml-clear-trained-model-deployment-cache
      parameters:
      - in: path
        name: model_id
        description: The unique identifier of the trained model.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  cleared:
                    type: boolean
                required:
                - cleared
              examples:
                MlClearTrainedModelDeploymentCacheResponseExample1:
                  description: A successful response when clearing the inference cache.
                  value: "{\n  \"cleared\": true\n}"
      x-state: Generally available; Added in 8.5.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
  /_ml/trained_models/{model_id}:
    get:
      tags:
      - ml trained model
      summary: Get trained model configuration info
      description: '


        ## Required authorization


        * Cluster privileges: `monitor_ml`

        '
      operationId: ml-get-trained-models
      parameters:
      - $ref: '#/components/parameters/ml.get_trained_models-model_id'
      - $ref: '#/components/parameters/ml.get_trained_models-allow_no_match'
      - $ref: '#/components/parameters/ml.get_trained_models-decompress_definition'
      - $ref: '#/components/parameters/ml.get_trained_models-exclude_generated'
      - $ref: '#/components/parameters/ml.get_trained_models-from'
      - $ref: '#/components/parameters/ml.get_trained_models-include'
      - $ref: '#/components/parameters/ml.get_trained_models-size'
      - $ref: '#/components/parameters/ml.get_trained_models-tags'
      responses:
        '200':
          $ref: '#/components/responses/ml.get_trained_models-200'
      x-state: Generally available; Added in 7.10.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
    put:
      tags:
      - ml trained model
      summary: Create a trained model
      description: 'Enable you to supply a trained model that is not created by data frame analytics.


        ## Required authorization


        * Cluster privileges: `manage_ml`

        '
      operationId: ml-put-trained-model
      parameters:
      - in: path
        name: model_id
        description: The unique identifier of the trained model.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: defer_definition_decompression
        description: 'If set to `true` and a `compressed_definition` is provided,

          the request defers definition decompression and skips relevant

          validations.'
        deprecated: false
        schema:
          default: false
          type: boolean
        x-state: Generally available; Added in 8.0.0
        style: form
      - in: query
        name: wait_for_completion
        description: 'Whether to wait for all child operations (e.g. model download)

          to complete.'
        deprecated: false
        schema:
          default: false
          type: boolean
        x-state: Generally available; Added in 8.8.0
        style: form
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                compressed_definition:
                  description: 'The compressed (GZipped and Base64 encoded) inference definition of the

                    model. If compressed_definition is specified, then definition cannot be

                    specified.'
                  type: string
                definition:
                  description: 'The inference definition for the model. If definition is specified, then

                    compressed_definition cannot be specified.'
                  allOf:
                  - $ref: '#/components/schemas/ml.put_trained_model.Definition'
                description:
                  description: A human-readable description of the inference trained model.
                  type: string
                inference_config:
                  description: 'The default configuration for inference. This can be either a regression

                    or classification configuration. It must match the underlying

                    definition.trained_model''s target_type. For pre-packaged models such as

                    ELSER the config is not required.'
                  allOf:
                  - $ref: '#/components/schemas/ml._types.InferenceConfigCreateContainer'
                input:
                  description: The input field names for the model definition.
                  allOf:
                  - $ref: '#/components/schemas/ml.put_trained_model.Input'
                metadata:
                  description: An object map that contains metadata about the model.
                  type: object
                model_type:
                  description: The model type.
                  default: tree_ensemble
                  allOf:
                  - $ref: '#/components/schemas/ml._types.TrainedModelType'
                model_size_bytes:
                  description: 'The estimated memory usage in bytes to keep the trained model in memory.

                    This property is supported only if defer_definition_decompression is true

                    or the model definition is not supplied.'
                  type: number
                platform_architecture:
                  description: 'The platform architecture (if applicable) of the trained mode. If the model

                    only works on one platform, because it is heavily optimized for a particular

                    processor architecture and OS combination, then this field specifies which.

                    The format of the string must match the platform identifiers used by Elasticsearch,

                    so one of, `linux-x86_64`, `linux-aarch64`, `darwin-aarch64`,

                    or `windows-x86_64`. For portable models (those that work independent of processor

                    architecture or OS features), leave this field unset.'
                  type: string
                tags:
                  description: An array of tags to organize the model.
                  type: array
                  items:
                    type: string
                prefix_strings:
                  description: Optional prefix strings applied at inference
                  x-state: Generally available; Added in 8.12.0
                  allOf:
                  - $ref: '#/components/schemas/ml._types.TrainedModelPrefixStrings'
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/ml._types.TrainedModelConfig'
      x-state: Generally available; Added in 7.10.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
    delete:
      tags:
      - ml trained model
      summary: Delete an unreferenced trained model
      description: 'The request deletes a trained inference model that is not referenced by an ingest pipeline.


        ## Required authorization


        * Cluster privileges: `manage_ml`

        '
      operationId: ml-delete-trained-model
      parameters:
      - in: path
        name: model_id
        description: The unique identifier of the trained model.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: force
        description: Forcefully deletes a trained model that is referenced by ingest pipelines or has a started deployment.
        deprecated: false
        schema:
          type: boolean
        style: form
      - in: query
        name: timeout
        description: Period to wait for a response. If no response is received before the timeout expires, the request fails and returns an error.
        deprecated: false
        schema:
          default: 30s
          allOf:
          - $ref: '#/components/schemas/_types.Duration'
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_types.AcknowledgedResponseBase'
              examples:
                MlDeleteTrainedModelResponseExample1:
                  description: A successful response when deleting an existing trained inference model.
                  value: "{\n  \"acknowledged\": true\n}"
      x-state: Generally available; Added in 7.10.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
  /_ml/trained_models/{model_id}/model_aliases/{model_alias}:
    put:
      tags:
      - ml trained model
      summary: Create or update a trained model alias
      description: 'A trained model alias is a logical name used to reference a single trained

        model.

        You can use aliases instead of trained model identifiers to make it easier to

        reference your models. For example, you can use aliases in inference

        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.

        If you use this API to update an alias such that it references a different

        trained model ID and the model uses a different type of data frame analytics,

        an error occurs. For example, this situation occurs if you have a trained

        model for regression analysis and a trained model for classification

        analysis; you cannot reassign an alias from one type of trained model to

        another.

        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.


        ## Required authorization


        * Cluster privileges: `manage_ml`

        '
      operationId: ml-put-trained-model-alias
      parameters:
      - in: path
        name: model_id
        description: The identifier for the trained model that the alias refers to.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: path
        name: model_alias
        description: The alias to create or update. This value cannot end in numbers.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Name'
        style: simple
      - in: query
        name: reassign
        description: '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.'
        deprecated: false
        schema:
          default: false
          type: boolean
        style: form
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_types.AcknowledgedResponseBase'
      x-state: Generally available; Added in 7.13.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
    delete:
      tags:
      - ml trained model
      summary: Delete a trained model alias
      description: 'This API deletes an existing model alias that refers to a trained model. If

        the model alias is missing or refers to a model other than the one identified

        by the `model_id`, this API returns an error.


        ## Required authorization


        * Cluster privileges: `manage_ml`

        '
      operationId: ml-delete-trained-model-alias
      parameters:
      - in: path
        name: model_id
        description: The trained model ID to which the model alias refers.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: path
        name: model_alias
        description: The model alias to delete.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Name'
        style: simple
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_types.AcknowledgedResponseBase'
              examples:
                MlDeleteTrainedModelAliasResponseExample1:
                  description: A successful response when deleting a trained model alias.
                  value: "{\n  \"acknowledged\": true\n}"
      x-state: Generally available; Added in 7.13.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
  /_ml/trained_models:
    get:
      tags:
      - ml trained model
      summary: Get trained model configuration info
      description: '


        ## Required authorization


        * Cluster privileges: `monitor_ml`

        '
      operationId: ml-get-trained-models-1
      parameters:
      - $ref: '#/components/parameters/ml.get_trained_models-allow_no_match'
      - $ref: '#/components/parameters/ml.get_trained_models-decompress_definition'
      - $ref: '#/components/parameters/ml.get_trained_models-exclude_generated'
      - $ref: '#/components/parameters/ml.get_trained_models-from'
      - $ref: '#/components/parameters/ml.get_trained_models-include'
      - $ref: '#/components/parameters/ml.get_trained_models-size'
      - $ref: '#/components/parameters/ml.get_trained_models-tags'
      responses:
        '200':
          $ref: '#/components/responses/ml.get_trained_models-200'
      x-state: Generally available; Added in 7.10.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
  /_ml/trained_models/{model_id}/_stats:
    get:
      tags:
      - ml trained model
      summary: Get trained models usage info
      description: 'You can get usage information for multiple trained

        models in a single API request by using a comma-separated list of model IDs or a wildcard expression.


        ## Required authorization


        * Cluster privileges: `monitor_ml`

        '
      operationId: ml-get-trained-models-stats
      parameters:
      - $ref: '#/components/parameters/ml.get_trained_models_stats-model_id'
      - $ref: '#/components/parameters/ml.get_trained_models_stats-allow_no_match'
      - $ref: '#/components/parameters/ml.get_trained_models_stats-from'
      - $ref: '#/components/parameters/ml.get_trained_models_stats-size'
      responses:
        '200':
          $ref: '#/components/responses/ml.get_trained_models_stats-200'
      x-state: Generally available; Added in 7.10.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
  /_ml/trained_models/_stats:
    get:
      tags:
      - ml trained model
      summary: Get trained models usage info
      description: 'You can get usage information for multiple trained

        models in a single API request by using a comma-separated list of model IDs or a wildcard expression.


        ## Required authorization


        * Cluster privileges: `monitor_ml`

        '
      operationId: ml-get-trained-models-stats-1
      parameters:
      - $ref: '#/components/parameters/ml.get_trained_models_stats-allow_no_match'
      - $ref: '#/components/parameters/ml.get_trained_models_stats-from'
      - $ref: '#/components/parameters/ml.get_trained_models_stats-size'
      responses:
        '200':
          $ref: '#/components/responses/ml.get_trained_models_stats-200'
      x-state: Generally available; Added in 7.10.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
  /_ml/trained_models/{model_id}/_infer:
    post:
      tags:
      - ml trained model
      summary: Evaluate a trained model
      operationId: ml-infer-trained-model
      parameters:
      - in: path
        name: model_id
        description: The unique identifier of the trained model.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: timeout
        description: Controls the amount of time to wait for inference results.
        deprecated: false
        schema:
          default: 10s
          allOf:
          - $ref: '#/components/schemas/_types.Duration'
        style: form
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                docs:
                  description: 'An array of objects to pass to the model for inference. The objects should contain a fields matching your

                    configured trained model input. Typically, for NLP models, the field name is `text_field`.

                    Currently, for NLP models, only a single value is allowed.'
                  type: array
                  items:
                    type: object
                    additionalProperties:
                      type: object
                inference_config:
                  description: The inference configuration updates to apply on the API call
                  allOf:
                  - $ref: '#/components/schemas/ml._types.InferenceConfigUpdateContainer'
              required:
              - docs
            examples:
              MlInferTrainedModelExample1:
                description: An example body for a `POST _ml/trained_models/lang_ident_model_1/_infer` request.
                value: "{\n  \"docs\":[{\"text\": \"The fool doth think he is wise, but the wise man knows himself to be a fool.\"}]\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  inference_results:
                    type: array
                    items:
                      $ref: '#/components/schemas/ml._types.InferenceResponseResult'
                required:
                - inference_results
      x-state: Generally available; Added in 8.3.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
  /_ml/trained_models/{model_id}/definition/{part}:
    put:
      tags:
      - ml trained model
      summary: Create part of a trained model definition
      description: '


        ## Required authorization


        * Cluster privileges: `manage_ml`

        '
      operationId: ml-put-trained-model-definition-part
      parameters:
      - in: path
        name: model_id
        description: The unique identifier of the trained model.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: path
        name: part
        description: 'The definition part number. When the definition is loaded for inference the definition parts are streamed in the

          order of their part number. The first part must be `0` and the final part must be `total_parts - 1`.'
        required: true
        deprecated: false
        schema:
          type: number
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                definition:
                  description: The definition part for the model. Must be a base64 encoded string.
                  type: string
                total_definition_length:
                  description: The total uncompressed definition length in bytes. Not base64 encoded.
                  type: number
                total_parts:
                  description: The total number of parts that will be uploaded. Must be greater than 0.
                  type: number
              required:
              - definition
              - total_definition_length
              - total_parts
            examples:
              MlPutTrainedModelDefinitionPartExample1:
                description: An example body for a `PUT _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/definition/0` request.
                value: "{\n    \"definition\": \"...\",\n    \"total_definition_length\": 265632637,\n    \"total_parts\": 64\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_types.AcknowledgedResponseBase'
      x-state: Generally available; Added in 8.0.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
  /_ml/trained_models/{model_id}/vocabulary:
    put:
      tags:
      - ml trained model
      summary: Create a trained model vocabulary
      description: 'This API is supported only for natural language processing (NLP) models.

        The vocabulary is stored in the index as described in `inference_config.*.vocabulary` of the trained model definition.


        ## Required authorization


        * Cluster privileges: `manage_ml`

        '
      operationId: ml-put-trained-model-vocabulary
      parameters:
      - in: path
        name: model_id
        description: The unique identifier of the trained model.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                vocabulary:
                  description: The model vocabulary, which must not be empty.
                  type: array
                  items:
                    type: string
                merges:
                  description: The optional model merges if required by the tokenizer.
                  x-state: Generally available; Added in 8.2.0
                  type: array
                  items:
                    type: string
                scores:
                  description: The optional vocabulary value scores if required by the tokenizer.
                  x-state: Generally available; Added in 8.9.0
                  type: array
                  items:
                    type: number
              required:
              - vocabulary
            examples:
              MlPutTrainedModelVocabularyExample1:
                description: An example body for a `PUT _ml/trained_models/elastic__distilbert-base-uncased-finetuned-conll03-english/vocabulary` request.
                value: "{\n  \"vocabulary\": [\n    \"[PAD]\",\n    \"[unused0]\",\n  ]\n}"
        required: true
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/_types.AcknowledgedResponseBase'
      x-state: Generally available; Added in 8.0.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
  /_ml/trained_models/{model_id}/deployment/_start:
    post:
      tags:
      - ml trained model
      summary: Start a trained model deployment
      description: 'It allocates the model to every machine learning node.


        ## Required authorization


        * Cluster privileges: `manage_ml`

        '
      operationId: ml-start-trained-model-deployment
      parameters:
      - in: path
        name: model_id
        description: The unique identifier of the trained model. Currently, only PyTorch models are supported.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: cache_size
        description: 'The inference cache size (in memory outside the JVM heap) per node for the model.

          The default value is the same size as the `model_size_bytes`. To disable the cache,

          `0b` can be provided.'
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.ByteSize'
        style: form
      - in: query
        name: deployment_id
        description: A unique identifier for the deployment of the model.
        deprecated: false
        schema:
          type: string
        x-state: Generally available; Added in 8.8.0
        style: form
      - in: query
        name: number_of_allocations
        description: 'The number of model allocations on each node where the model is deployed.

          All allocations on a node share the same copy of the model in memory but use

          a separate set of threads to evaluate the model.

          Increasing this value generally increases the throughput.

          If this setting is greater than the number of hardware threads

          it will automatically be changed to a value less than the number of hardware threads.

          If adaptive_allocations is enabled, do not set this value, because it’s automatically set.'
        deprecated: false
        schema:
          default: 1.0
          type: number
        style: form
      - in: query
        name: priority
        description: The deployment priority
        deprecated: false
        schema:
          $ref: '#/components/schemas/ml._types.TrainingPriority'
        style: form
      - in: query
        name: queue_capacity
        description: 'Specifies the number of inference requests that are allowed in the queue. After the number of requests exceeds

          this value, new requests are rejected with a 429 error.'
        deprecated: false
        schema:
          default: 1024.0
          type: number
        style: form
      - in: query
        name: threads_per_allocation
        description: 'Sets the number of threads used by each model allocation during inference. This generally increases

          the inference speed. The inference process is a compute-bound process; any number

          greater than the number of available hardware threads on the machine does not increase the

          inference speed. If this setting is greater than the number of hardware threads

          it will automatically be changed to a value less than the number of hardware threads.'
        deprecated: false
        schema:
          default: 1.0
          type: number
        style: form
      - in: query
        name: timeout
        description: Specifies the amount of time to wait for the model to deploy.
        deprecated: false
        schema:
          default: 20s
          allOf:
          - $ref: '#/components/schemas/_types.Duration'
        style: form
      - in: query
        name: wait_for
        description: Specifies the allocation status to wait for before returning.
        deprecated: false
        schema:
          default: started
          allOf:
          - $ref: '#/components/schemas/ml._types.DeploymentAllocationState'
        style: form
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                adaptive_allocations:
                  description: 'Adaptive allocations configuration. When enabled, the number of allocations

                    is set based on the current load.

                    If adaptive_allocations is enabled, do not set the number of allocations manually.'
                  allOf:
                  - $ref: '#/components/schemas/ml._types.AdaptiveAllocationsSettings'
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  assignment:
                    allOf:
                    - $ref: '#/components/schemas/ml._types.TrainedModelAssignment'
                required:
                - assignment
      x-state: Generally available; Added in 8.0.0
      x-metaTags:
      - content: Elasticsearch, Machine Learning
        name: product_name
  /_ml/trained_models/{model_id}/deployment/_stop:
    post:
      tags:
      - ml trained model
      summary: Stop a trained model deployment
      description: '


        ## Required authorization


        * Cluster privileges: `manage_ml`

        '
      operationId: ml-stop-trained-model-deployment
      parameters:
      - in: path
        name: model_id
        description: The unique identifier of the trained model.
        required: true
        deprecated: false
        schema:
          $ref: '#/components/schemas/_types.Id'
        style: simple
      - in: query
        name: allow_no_match
        description: 'Specifies what to do when the request: contains wildcard expressions and there are no deployments that match;

          contains the  `_all` string or no identifiers and there are no matches; or contains wildcard expressions and

          there are only partial matches. By default, it returns an empty array when there are no matches and the subset of results when there are partial matches.

          If `false`, the request returns a 404 status code when there are no matches or only partial matches.'
        deprecated: false
        schema:
          default: true
          type: boolean
        style: form
      - in: query
        name: force
        description: 'Forcefully stops the deployment, even if it is used by ingest pipelines. You can''t use these pipelines until you

          restart the model deployment.'
        deprecated: false
        schema:
          default: false
          type: boolean
        style: form
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                id:
                  description: If provided, must be the same identifier as in the path.
                  allOf:
                  - $ref: '#/components/schemas/_types.Id'
                allow_no_match:
                  description: 'Specifies what to do when the request: contains wildcard expressions and there are no deployments that match;

                    contains the  `_all` string or no identifiers and there are no matches; or contains wildcard expressions and

                    there are only partial matches. By default, it returns an empty array when there are no matches and the subset of results when there are partial matches.

                    If `false`, the request returns a 404 status code when there are no matches or only partial matches.'
                  default: true
                  type: boolean
                force:
                  description: 'Forcefully stops the deployment, even if it is used by ingest pipelines. You can''t use these pipelines until you

                    restart the model deployment.'
                  default: false
                  type: boolean
      responses:
        '200':
          description: ''
          content:
            application/json:
              schema:
                type: object
                properties:
                  stopped:
                    type: boolean
                required:
                - stopped
      x-

# --- truncated at 32 KB (418 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/elk-stack/refs/heads/main/openapi/elk-stack-ml-trained-model-api-openapi.yml