# 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 Node API
  version: 1.0.0
extends: openapi/scope3-node-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: 5
- target: $.paths['/node'].get
  update:
    x-apievangelist-phrasing:
      intent: List compute nodes for AI impact modeling
      effect: read
      questions:
      - Which compute nodes are available for AI emissions modeling?
      - Can I filter nodes by cloud, GPU type or managed service?
      - How do I see only the custom nodes I created?
      instructions:
      - text: List all global and custom nodes.
      - text: List nodes on cloud {cloud} that use GPU {gpu}.
        slots:
          cloud: query.cloud
          gpu: query.gpu
      method: generated
      generated: '2026-10-01'
- target: $.paths['/node'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a custom compute node
      effect: write
      questions:
      - Can I define my own hardware node with a specific GPU and CPU count?
      - What hardware details are needed to model a custom node's footprint?
      instructions:
      - text: Create custom node {id} with {gpu_count} x {gpu_id} GPUs and {cpu_count} CPUs.
        slots:
          id: requestBody.id
          gpu_count: requestBody.gpu_count
          gpu_id: requestBody.gpu_id
          cpu_count: requestBody.cpu_count
      - text: Add node {id} on cloud {cloud_id} with {gpu_count} {gpu_id} GPUs, {cpu_count} CPUs and a {use_life_years}-year use life.
        slots:
          id: requestBody.id
          cloud_id: requestBody.cloud_id
          gpu_count: requestBody.gpu_count
          gpu_id: requestBody.gpu_id
          cpu_count: requestBody.cpu_count
          use_life_years: requestBody.use_life_years
      method: generated
      generated: '2026-10-01'
- target: $.paths['/node/{nodeId}'].get
  update:
    x-apievangelist-phrasing:
      intent: View one compute node
      effect: read
      questions:
      - What GPU, CPU and embodied emissions values does a given node use?
      - Can I look up a single node's specs by its id?
      instructions:
      - text: Show node {node_id}.
        slots:
          node_id: path.nodeId
      - text: Get the hardware specs of node {node_id}.
        slots:
          node_id: path.nodeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/node/{nodeId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a custom compute node
      effect: write
      questions:
      - Can I change the utilization rate on a node I defined?
      - Am I allowed to edit global nodes or only my custom ones?
      instructions:
      - text: Set the average utilization of node {node_id} to {utilization}.
        slots:
          node_id: path.nodeId
          utilization: requestBody.average_utilization_rate
      - text: Change node {node_id} to use {gpu_count} GPUs of type {gpu_id}.
        slots:
          node_id: path.nodeId
          gpu_count: requestBody.gpu_count
          gpu_id: requestBody.gpu_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/node/{nodeId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a custom compute node
      effect: destructive
      questions:
      - How do I remove a custom node I no longer need?
      - Can I delete a global node, or only custom ones?
      instructions:
      - text: Delete node {node_id}.
        slots:
          node_id: path.nodeId
      - text: Remove my custom node {node_id}.
        slots:
          node_id: path.nodeId
      method: generated
      generated: '2026-10-01'