# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for AI impact measurement Model API
  version: 1.0.0
extends: openapi/scope3-model-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: 7
- target: $.paths['/model'].get
  update:
    x-apievangelist-phrasing:
      intent: List AI models
      effect: read
      questions:
      - Which AI models are available for impact measurement?
      - Can I list models from one model family only?
      instructions:
      - text: List all AI models.
      - text: List models in family {family}.
        slots:
          family: query.family
      method: generated
      generated: '2026-10-01'
- target: $.paths['/model'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a custom AI model
      effect: write
      questions:
      - How do I add my own fine-tuned model so its footprint can be estimated?
      - Can I record training energy and emissions for a custom model?
      instructions:
      - text: Create model {id}.
        slots:
          id: requestBody.id
      - text: Register model {id} named {name} with {total_params_billions} billion parameters.
        slots:
          id: requestBody.id
          name: requestBody.name
          total_params_billions: requestBody.total_params_billions
      - text: Add custom model {id} fine-tuned from {fine_tuned_from_model_id}.
        slots:
          id: requestBody.id
          fine_tuned_from_model_id: requestBody.fine_tuned_from_model_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/model/{modelId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an AI model's details
      effect: read
      questions:
      - What parameters and training footprint are recorded for a model?
      - Can I look up a global or custom model by ID?
      instructions:
      - text: Get model {modelId}.
        slots:
          modelId: path.modelId
      - text: Show the training emissions recorded for model {modelId}.
        slots:
          modelId: path.modelId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/model/{modelId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an AI model
      effect: write
      questions:
      - Can I correct the parameter count or training energy on a model?
      - How do I change the estimated requests per day for a model?
      instructions:
      - text: Set training energy of model {modelId} to {training_usage_energy_kwh} kWh.
        slots:
          modelId: path.modelId
          training_usage_energy_kwh: requestBody.training_usage_energy_kwh
      - text: Update model {modelId} to {estimated_requests_per_day} requests per day.
        slots:
          modelId: path.modelId
          estimated_requests_per_day: requestBody.estimated_requests_per_day
      method: generated
      generated: '2026-10-01'
- target: $.paths['/model/{modelId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an AI model
      effect: destructive
      questions:
      - Can I remove a custom model I registered?
      - Is deleting a model permanent?
      instructions:
      - text: Delete model {modelId}.
        slots:
          modelId: path.modelId
      - text: Remove custom model {modelId}.
        slots:
          modelId: path.modelId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/model/{modelId}/alias'].put
  update:
    x-apievangelist-phrasing:
      intent: Add an alias to a model
      effect: write
      questions:
      - Can a model be known by more than one name?
      - How do I map an alternate model name to an existing model?
      instructions:
      - text: Add alias {alias} to model {modelId}.
        slots:
          alias: requestBody.alias
          modelId: path.modelId
      - text: Let {alias} also refer to model {modelId}.
        slots:
          alias: requestBody.alias
          modelId: path.modelId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/model/{modelId}/alias/{alias}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove an alias from a model
      effect: destructive
      questions:
      - Can I drop an old alias from a model?
      - What happens to an alias I remove?
      instructions:
      - text: Remove alias {alias} from model {modelId}.
        slots:
          alias: path.alias
          modelId: path.modelId
      - text: Stop {alias} pointing to model {modelId}.
        slots:
          alias: path.alias
          modelId: path.modelId
      method: generated
      generated: '2026-10-01'