# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Elasticsearch Request & Response Specification ml trained model API
  version: 1.0.0
extends: openapi/elk-stack-ml-trained-model-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 15
- target: $.paths['/_ml/trained_models/{model_id}/deployment/cache/_clear'].post
  update:
    x-apievangelist-phrasing:
      intent: Clear a trained model deployment's inference cache
      effect: write
      questions:
      - Can I clear the inference cache of a deployed model without restarting the deployment?
      - How do I flush cached model responses on every node a model is assigned to?
      instructions:
      - text: Clear the deployment inference cache for model {model_id}.
        slots:
          model_id: path.model_id
      - text: Flush cached responses for deployed model {model_id} on all nodes.
        slots:
          model_id: path.model_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get trained model configs by ID
      effect: read
      questions:
      - What inference config and metadata does a particular trained model have?
      - Can I include the decompressed model definition when fetching a trained model?
      instructions:
      - text: Show the configuration of trained model {model_id}.
        slots:
          model_id: path.model_id
      - text: Get trained model {model_id} including {include}.
        slots:
          model_id: path.model_id
          include: query.include
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Upload a trained model
      effect: write
      questions:
      - How do I bring in a model that wasn't created by data frame analytics?
      - Can I tag a trained model and give it a description when I create it?
      instructions:
      - text: Create trained model {model_id} with inference config {inference_config}.
        slots:
          model_id: path.model_id
          inference_config: requestBody.inference_config
      - text: Upload model {model_id} of type {model_type} tagged {tags}.
        slots:
          model_id: path.model_id
          model_type: requestBody.model_type
          tags: requestBody.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an unreferenced trained model
      effect: destructive
      questions:
      - How do I delete a trained model that no ingest pipeline uses anymore?
      - Can I force-delete a trained model?
      instructions:
      - text: Delete trained model {model_id}.
        slots:
          model_id: path.model_id
      - text: Force delete the trained model {model_id} within {timeout}.
        slots:
          model_id: path.model_id
          timeout: query.timeout
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}/model_aliases/{model_alias}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or reassign a trained model alias
      effect: write
      questions:
      - Can I give a trained model a friendly alias to use in inference processors?
      - How do I move an alias from an old model to a newly trained one?
      instructions:
      - text: Point alias {model_alias} at trained model {model_id}.
        slots:
          model_alias: path.model_alias
          model_id: path.model_id
      - text: Reassign alias {model_alias} to model {model_id}.
        slots:
          model_alias: path.model_alias
          model_id: path.model_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}/model_aliases/{model_alias}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a trained model alias
      effect: destructive
      questions:
      - How do I remove an alias from a trained model?
      - What happens if I delete an alias that points to a different model than the one I name?
      instructions:
      - text: Delete alias {model_alias} from trained model {model_id}.
        slots:
          model_alias: path.model_alias
          model_id: path.model_id
      - text: Remove the model alias {model_alias} that refers to {model_id}.
        slots:
          model_alias: path.model_alias
          model_id: path.model_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models'].get
  update:
    x-apievangelist-phrasing:
      intent: List all trained models
      effect: read
      questions:
      - What trained models are available on my cluster?
      - Can I list only the trained models with certain tags?
      instructions:
      - text: List all trained models.
      - text: List trained models tagged {tags}.
        slots:
          tags: query.tags
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}/_stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get usage stats for specific trained models
      effect: read
      questions:
      - How many inference calls has a specific trained model served?
      - Can I get deployment and ingest stats for a few models using a wildcard?
      instructions:
      - text: Show usage stats for trained model {model_id}.
        slots:
          model_id: path.model_id
      - text: Get inference and deployment statistics for models matching {model_id}.
        slots:
          model_id: path.model_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/_stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get usage stats for all trained models
      effect: read
      questions:
      - Which of my trained models are actually being used?
      - Can I see usage statistics across every trained model on the cluster?
      instructions:
      - text: Show usage stats for all trained models.
      - text: Get stats for the first {size} trained models.
        slots:
          size: query.size
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}/_infer'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a trained model on documents
      effect: read
      questions:
      - Can I test a deployed trained model by sending it a few documents directly?
      - How do I override the inference config when evaluating a trained model on sample docs?
      instructions:
      - text: 'Run trained model {model_id} on these documents: {docs}.'
        slots:
          model_id: path.model_id
          docs: requestBody.docs
      - text: Infer {docs} with model {model_id} using config {inference_config}.
        slots:
          docs: requestBody.docs
          model_id: path.model_id
          inference_config: requestBody.inference_config
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}/definition/{part}'].put
  update:
    x-apievangelist-phrasing:
      intent: Upload one part of a model definition
      effect: write
      questions:
      - How do I upload a large model definition in several chunks?
      - What do I need to tell Elasticsearch about the total parts and total length when uploading a definition piece?
      instructions:
      - text: Upload part {part} of the definition for model {model_id}.
        slots:
          part: path.part
          model_id: path.model_id
      - text: Store definition chunk {part} of {total_parts} for model {model_id}.
        slots:
          part: path.part
          total_parts: requestBody.total_parts
          model_id: path.model_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}/vocabulary'].put
  update:
    x-apievangelist-phrasing:
      intent: Upload an NLP model's vocabulary
      effect: write
      questions:
      - How do I add the tokenizer vocabulary for an NLP model I uploaded?
      - Can I include BPE merges when storing a trained model vocabulary?
      instructions:
      - text: Upload vocabulary {vocabulary} for NLP model {model_id}.
        slots:
          vocabulary: requestBody.vocabulary
          model_id: path.model_id
      - text: Store the vocabulary and merges {merges} for model {model_id}.
        slots:
          merges: requestBody.merges
          model_id: path.model_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}/deployment/_start'].post
  update:
    x-apievangelist-phrasing:
      intent: Deploy a trained model to ML nodes
      effect: write
      questions:
      - How do I deploy a trained model so it can serve inference?
      - Can I choose the number of allocations and threads per allocation when starting a deployment?
      instructions:
      - text: Start a deployment of trained model {model_id}.
        slots:
          model_id: path.model_id
      - text: Deploy {model_id} with {number_of_allocations} allocations and {threads_per_allocation} threads each.
        slots:
          model_id: path.model_id
          number_of_allocations: query.number_of_allocations
          threads_per_allocation: query.threads_per_allocation
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}/deployment/_stop'].post
  update:
    x-apievangelist-phrasing:
      intent: Stop a trained model deployment
      effect: write
      questions:
      - How do I undeploy a trained model to free up ML node memory?
      - Can I force-stop a model deployment that ingest pipelines still reference?
      instructions:
      - text: Stop the deployment of trained model {model_id}.
        slots:
          model_id: path.model_id
      - text: Force stop the deployed model {model_id}.
        slots:
          model_id: path.model_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/_ml/trained_models/{model_id}/deployment/_update'].post
  update:
    x-apievangelist-phrasing:
      intent: Scale a trained model deployment
      effect: write
      questions:
      - Can I change the number of allocations on a model that's already deployed?
      - How do I turn on adaptive allocations for a running model deployment?
      instructions:
      - text: Scale the deployment of {model_id} to {number_of_allocations} allocations.
        slots:
          model_id: path.model_id
          number_of_allocations: requestBody.number_of_allocations
      - text: Enable adaptive allocations {adaptive_allocations} on deployed model {model_id}.
        slots:
          adaptive_allocations: requestBody.adaptive_allocations
          model_id: path.model_id
      method: generated
      generated: '2026-09-26'