# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for DoiT Cloud Diagrams API
  version: 1.0.0
extends: openapi/doit-cloud-diagrams-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: 12
- target: $.paths['/clouddiagrams/v1/scheme/find'].post
  update:
    x-apievangelist-phrasing:
      intent: Find diagrams containing given resources
      effect: read
      questions:
      - Which cloud diagrams include a particular resource?
      - Can I get diagram links for a list of resource IDs?
      instructions:
      - text: Find diagrams that contain resources {resources}.
        slots:
          resources: requestBody.resources
      - text: Get diagram URLs for resource IDs {resources}.
        slots:
          resources: requestBody.resources
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/scheme/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get diagram activity stats for a period
      effect: read
      questions:
      - How active were our cloud diagrams over the last month?
      - Can I see activity statistics for every diagram between two dates?
      instructions:
      - text: Get diagram activity stats from {start} to {end}.
        slots:
          start: query.start
          end: query.end
      - text: Show all diagrams with their activity between {start} and {end}.
        slots:
          start: query.start
          end: query.end
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/scheme/get'].post
  update:
    x-apievangelist-phrasing:
      intent: Get diagrams and their components
      effect: read
      questions:
      - How do I pull the full component data for a diagram?
      - Can I skip empty subnets or the default VPC when fetching diagram components?
      instructions:
      - text: Get components of diagram {scheme}.
        slots:
          scheme: requestBody.scheme
      - text: Get components of layer {statussheet} excluding the default VPC ({exclude_default_vpc}).
        slots:
          statussheet: requestBody.statussheet
          exclude_default_vpc: query.exclude_default_vpc
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/scheme/search'].post
  update:
    x-apievangelist-phrasing:
      intent: Search diagrams and components by text
      effect: read
      questions:
      - Can I search across my diagrams for a component by name or property value?
      - How do I find which diagram layer mentions a certain term?
      instructions:
      - text: Search diagrams for {query}.
        slots:
          query: requestBody.query
      - text: Search layer {ss_id} for components matching {query}.
        slots:
          ss_id: requestBody.ss_id
          query: requestBody.query
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/statussheet/{id}/get'].post
  update:
    x-apievangelist-phrasing:
      intent: Get specific components from a layer
      effect: read
      questions:
      - How do I fetch particular nodes or links from one diagram layer?
      - Can I request only certain component IDs from a layer?
      instructions:
      - text: Get nodes {node} from layer {id}.
        slots:
          node: requestBody.node
          id: path.id
      - text: Get links {link} from diagram layer {id}.
        slots:
          link: requestBody.link
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/statussheet/{id}/export-json'].get
  update:
    x-apievangelist-phrasing:
      intent: Export a diagram layer as JSON
      effect: read
      questions:
      - Can I export a whole diagram to JSON?
      - How do I download a layer's components as structured data?
      instructions:
      - text: Export layer {id} as JSON.
        slots:
          id: path.id
      - text: Download the full JSON export of diagram layer {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/statussheet/{id}/costs'].get
  update:
    x-apievangelist-phrasing:
      intent: Get costs for a diagram layer
      effect: read
      questions:
      - How much did the infrastructure in a diagram cost over a date range?
      - Can I see period-over-period spend for one diagram layer?
      instructions:
      - text: Get costs for layer {id} from {startDate} to {endDate}.
        slots:
          id: path.id
          startDate: query.startDate
          endDate: query.endDate
      - text: Show {interval} spend for diagram layer {id} between {startDate} and {endDate}.
        slots:
          interval: query.interval
          id: path.id
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/statussheet/{id}/snapshots'].get
  update:
    x-apievangelist-phrasing:
      intent: List saved snapshots of a layer
      effect: read
      questions:
      - What snapshots have been saved for a diagram layer?
      - Can I page through a layer's snapshot history?
      instructions:
      - text: List snapshots for layer {id}.
        slots:
          id: path.id
      - text: List the latest {limit} snapshots of layer {id}.
        slots:
          limit: query.limit
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/statussheet/{id}/snapshot'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one snapshot of a layer
      effect: read
      questions:
      - How do I view a past snapshot of a diagram layer?
      - Can I open a specific layer snapshot by its ID?
      instructions:
      - text: Get snapshot {snapshot_id} of layer {id}.
        slots:
          snapshot_id: query.snapshot_id
          id: path.id
      - text: Open layer {id} as it was in snapshot {snapshot_id}.
        slots:
          snapshot_id: query.snapshot_id
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/statussheet/{id}/resources/{rid}/relationships'].get
  update:
    x-apievangelist-phrasing:
      intent: Find resources related to a resource
      effect: read
      questions:
      - What other resources are connected to this one in the diagram?
      - Can I walk upstream or downstream dependencies to a set depth?
      instructions:
      - text: Show resources related to {rid} in layer {id}.
        slots:
          rid: path.rid
          id: path.id
      - text: Walk {direction} from resource {rid} in layer {id} to depth {depth}.
        slots:
          direction: query.direction
          rid: path.rid
          id: path.id
          depth: query.depth
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/activity'].get
  update:
    x-apievangelist-phrasing:
      intent: List change activity for a layer
      effect: read
      questions:
      - What changed recently in a diagram layer?
      - Can I filter a layer's activity groups by tag?
      instructions:
      - text: List activity groups for layer {ss_id}.
        slots:
          ss_id: query.ss_id
      - text: List activity for layer {ss_id} tagged {tags}.
        slots:
          ss_id: query.ss_id
          tags: query.tags
      method: generated
      generated: '2026-10-01'
- target: $.paths['/clouddiagrams/v1/activity/node-activities'].get
  update:
    x-apievangelist-phrasing:
      intent: List activity for one component node
      effect: read
      questions:
      - What changes happened to a specific node in a diagram?
      - Can I see an individual component's activity history?
      instructions:
      - text: List activities for node {nodeId} in layer {ss_id}.
        slots:
          nodeId: query.nodeId
          ss_id: query.ss_id
      - text: Show the change history of component {nodeId} on layer {ss_id}.
        slots:
          nodeId: query.nodeId
          ss_id: query.ss_id
      method: generated
      generated: '2026-10-01'