# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Microsoft Azure Models API
  version: 1.0.0
extends: openapi/microsoft-azure-models-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-01'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 17
- target: $.paths['/subscriptions/{subscriptionId}/providers/Microsoft.CognitiveServices/models'].get
  update:
    x-apievangelist-phrasing:
      intent: List Azure AI models available to a subscription
      effect: read
      questions:
      - Which Cognitive Services models can my subscription deploy?
      - What AI models are available to me in Azure AI services?
      instructions:
      - text: List the Cognitive Services models available to subscription {subscriptionId}.
        slots:
          subscriptionId: path.subscriptionId
      - text: Show the AI service model catalog I can use.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models'].get
  update:
    x-apievangelist-phrasing:
      intent: List Digital Twins models
      effect: read
      questions:
      - What DTDL models are uploaded to my Azure Digital Twins instance?
      - Can I list only the digital twin models a given model depends on?
      instructions:
      - text: List all DTDL models in my Digital Twins instance.
      - text: List the digital twin models needed by {dependenciesFor}, including definitions.
        slots:
          dependenciesFor: query.dependenciesFor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload Digital Twins models
      effect: write
      questions:
      - How do I upload DTDL model definitions to Azure Digital Twins?
      - If one of several uploaded twin models is invalid, are any of them saved?
      instructions:
      - text: Upload these DTDL models to my Digital Twins instance using API version {api-version}.
        slots:
          api-version: query.api-version
      - text: Add the new twin interface definitions as one batch.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one Digital Twins model by DTMI
      effect: read
      questions:
      - How do I look up one DTDL model in my Azure Digital Twins instance by its model id?
      - Can I fetch a twin model's full definition along with its metadata?
      instructions:
      - text: Get Digital Twins model {id}.
        slots:
          id: path.id
      - text: 'Show DTDL model {id} with its definition included: {includeModelDefinition}.'
        slots:
          id: path.id
          includeModelDefinition: query.includeModelDefinition
      method: generated
      generated: '2026-10-01'
- target: $.paths['/models/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a Digital Twins model
      effect: destructive
      questions:
      - Why does deleting a DTDL model fail when other twin models still reference it?
      - How do I remove a model from my Azure Digital Twins instance?
      instructions:
      - text: Delete Digital Twins model {id}.
        slots:
          id: path.id
      - text: Remove DTDL interface {id} from the twin graph's model set.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/models/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update Digital Twins model metadata
      effect: write
      questions:
      - Can I decommission a DTDL model with a JSON Patch instead of deleting it?
      - How do I change the metadata on an existing twin model?
      instructions:
      - text: Update the metadata of digital twin model {id} with a JSON Patch.
        slots:
          id: path.id
      - text: Decommission twin model {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{model_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a model by model_id
      effect: read
      questions:
      - Where do I look up details for a model using the model_id path form?
      - Can I fetch a model's details by passing its id as model_id?
      instructions:
      - text: Get details for model {model_id} via the model_id endpoint.
        slots:
          model_id: path.model_id
      - text: Look up model {model_id} (underscore model_id route).
        slots:
          model_id: path.model_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{model-id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a model by model-id (hyphenated route)
      effect: read
      questions:
      - Is there a hyphenated model-id route for reading a model's details?
      - How do I read one model's details through the dash-separated model-id path?
      instructions:
      - text: Get details for model {model-id} via the hyphenated model-id endpoint.
        slots:
          model-id: path.model-id
      - text: Look up model {model-id} using the dash-style route.
        slots:
          model-id: path.model-id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{model}/analyze'].post
  update:
    x-apievangelist-phrasing:
      intent: Analyze an image with a domain-specific model
      effect: read
      questions:
      - Can Computer Vision recognize celebrities or landmarks in a photo?
      - Which language can I get domain-specific image analysis results in?
      instructions:
      - text: Analyze this image with the {model} domain model.
        slots:
          model: path.model
      - text: Recognize {model} content in the image and answer in {language}.
        slots:
          model: path.model
          language: query.language
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{name}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom trained model
      effect: read
      questions:
      - How do I check the training status of a custom model I started?
      - Can I see a custom model's performance once training finishes?
      instructions:
      - text: Get custom model {name}.
        slots:
          name: path.name
      - text: Show training status and performance of model {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{name}'].put
  update:
    x-apievangelist-phrasing:
      intent: Train a custom model
      effect: write
      questions:
      - How do I start training a new custom model with my training parameters?
      - Can I kick off custom model training and evaluate it at the same time?
      instructions:
      - text: Start training custom model {name}.
        slots:
          name: path.name
      - text: Train model {name} with training parameters {trainingParameters}.
        slots:
          name: path.name
          trainingParameters: requestBody.trainingParameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{name}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom model
      effect: destructive
      questions:
      - Which training states must a custom model be in before I can delete it?
      - How do I get rid of a custom model I no longer need?
      instructions:
      - text: Delete custom model {name}.
        slots:
          name: path.name
      - text: Remove the finished or failed model {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{name}:cancel'].post
  update:
    x-apievangelist-phrasing:
      intent: Cancel custom model training
      effect: destructive
      questions:
      - Can I stop a custom model training run that is still in progress?
      - How do I cancel training to avoid spending more training minutes?
      instructions:
      - text: Cancel training of model {name}.
        slots:
          name: path.name
      - text: Stop the in-progress training job for {name}.
        slots:
          name: path.name
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{name}/evaluations/{evaluationName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a model evaluation
      effect: read
      questions:
      - How do I read the results of one evaluation run against my custom model?
      - What status is a specific model evaluation in?
      instructions:
      - text: Get evaluation {evaluationName} of model {name}.
        slots:
          name: path.name
          evaluationName: path.evaluationName
      - text: Show the performance results for evaluation {evaluationName}.
        slots:
          evaluationName: path.evaluationName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{name}/evaluations/{evaluationName}'].put
  update:
    x-apievangelist-phrasing:
      intent: Evaluate an existing custom model
      effect: write
      questions:
      - How do I run an evaluation of a trained model against a test set?
      - Can I create a new evaluation with its own evaluation parameters?
      instructions:
      - text: Evaluate model {name} as evaluation {evaluationName}.
        slots:
          name: path.name
          evaluationName: path.evaluationName
      - text: Run evaluation {evaluationName} on model {name} with parameters {evaluationParameters}.
        slots:
          name: path.name
          evaluationName: path.evaluationName
          evaluationParameters: requestBody.evaluationParameters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{name}/evaluations/{evaluationName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a model evaluation
      effect: destructive
      questions:
      - Can I delete an evaluation that is still running?
      - How do I remove an old evaluation from a custom model?
      instructions:
      - text: Delete evaluation {evaluationName} from model {name}.
        slots:
          name: path.name
          evaluationName: path.evaluationName
      - text: Remove the failed evaluation {evaluationName}.
        slots:
          evaluationName: path.evaluationName
      method: generated
      generated: '2026-09-26'
- target: $.paths['/models/{name}/evaluations'].get
  update:
    x-apievangelist-phrasing:
      intent: List evaluations for a custom model
      effect: read
      questions:
      - What evaluations have been run on my custom model so far?
      - Can I page through a model's evaluations with skip and top?
      instructions:
      - text: List evaluations of model {name}.
        slots:
          name: path.name
      - text: List the first {top} evaluations of model {name}, skipping {skip}.
        slots:
          name: path.name
          top: query.top
          skip: query.skip
      method: generated
      generated: '2026-09-26'