DoiT · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for DoiT Insights API

10 actions 10 updates phrasing extends openapi/doit-insights-api-openapi.yml
Generated by API Evangelist Written by API Evangelist tooling for DoiT's API. It is a proposal applied on top of the contract, not a document DoiT publishes.
View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 10

$.info
$.paths['/insights/v1/results'].get
$.paths['/insights/v1/results'].post
$.paths['/insights/v1/results'].delete
$.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}'].get
$.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}'].post
$.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}'].delete
$.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}/status'].put
$.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}/resource-results'].get
$.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}/resource-results'].post

OpenAPI Overlay

Raw ↑ 
# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for DoiT Insights API
  version: 1.0.0
extends: openapi/doit-insights-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: 9
- target: $.paths['/insights/v1/results'].get
  update:
    x-apievangelist-phrasing:
      intent: List optimization insights
      effect: read
      questions:
      - What cost savings opportunities has DoiT found for us?
      - Can I filter insights to only easy wins or by cloud provider?
      - Can I search insights by category or priority?
      instructions:
      - text: List insights in category {category}.
        slots:
          category: query.category
      - text: Show insights with priority {priority} for {cloudProvider}.
        slots:
          priority: query.priority
          cloudProvider: query.cloudProvider
      method: generated
      generated: '2026-10-01'
- target: $.paths['/insights/v1/results'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update insights in bulk
      effect: write
      questions:
      - Can I push many custom insights in a single request?
      - How do I upload my own optimization findings in batch?
      instructions:
      - text: Upload insights batch {results}.
        slots:
          results: requestBody.results
      - text: 'Create or update these insights in bulk: {results}.'
        slots:
          results: requestBody.results
      method: generated
      generated: '2026-10-01'
- target: $.paths['/insights/v1/results'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete insights by key in bulk
      effect: destructive
      questions:
      - How do I remove every insight with a given key from my batch source?
      - Does bulk deleting also remove resource results?
      instructions:
      - text: Delete all insights with key {insightKey}.
        slots:
          insightKey: query.insightKey
      - text: Bulk remove insights keyed {insightKey} and their resource results.
        slots:
          insightKey: query.insightKey
      method: generated
      generated: '2026-10-01'
- target: $.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}'].get
  update:
    x-apievangelist-phrasing:
      intent: Retrieve one insight summary
      effect: read
      questions:
      - How do I see the savings summary for a single insight?
      - Does fetching one insight include its resource-level results?
      instructions:
      - text: Get insight {insightKey} from source {sourceID}.
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
      - text: Show the summary of insight {insightKey} in {sourceID}.
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or update a single insight
      effect: write
      questions:
      - How do I publish one custom insight for a source?
      - What happens if an insight with the same key already exists?
      instructions:
      - text: 'Upsert insight {key} titled {title} in source {sourceID} under key {insightKey} for {cloudProvider}, categories {categories}: {shortDescription}.'
        slots:
          key: requestBody.key
          title: requestBody.title
          sourceID: path.sourceID
          insightKey: path.insightKey
          cloudProvider: requestBody.cloudProvider
          categories: requestBody.categories
          shortDescription: requestBody.shortDescription
      - text: Save insight {insightKey} for source {sourceID} with title {title}.
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
          title: requestBody.title
      method: generated
      generated: '2026-10-01'
- target: $.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a single insight
      effect: destructive
      questions:
      - How do I permanently delete one insight I created via the API?
      - Can I delete insights that weren't created through the public API?
      instructions:
      - text: Delete insight {insightKey} from source {sourceID}.
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
      - text: Permanently remove insight {insightKey} in {sourceID}.
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}/status'].put
  update:
    x-apievangelist-phrasing:
      intent: Acknowledge or dismiss an insight
      effect: write
      questions:
      - How do I mark an insight as acknowledged or dismissed?
      - Can I record why I dismissed an insight?
      instructions:
      - text: Set insight {insightKey} in {sourceID} to {status}.
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
          status: requestBody.status
      - text: Dismiss insight {insightKey} from {sourceID} with status {status} and details {dismissalDetails}.
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
          status: requestBody.status
          dismissalDetails: requestBody.dismissalDetails
      method: generated
      generated: '2026-10-01'
- target: $.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}/resource-results'].get
  update:
    x-apievangelist-phrasing:
      intent: List affected resources for an insight
      effect: read
      questions:
      - Which individual cloud resources does an insight apply to?
      - Can I page through an insight's resource-level results?
      instructions:
      - text: List resource results for insight {insightKey} in {sourceID}.
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
      - text: Show the affected resources of insight {insightKey} from {sourceID}.
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
      method: generated
      generated: '2026-10-01'
- target: $.paths['/insights/v1/results/source/{sourceID}/insight/{insightKey}/resource-results'].post
  update:
    x-apievangelist-phrasing:
      intent: Replace an insight's resource results
      effect: write
      questions:
      - How do I overwrite the list of resources attached to an insight?
      - What happens to existing resource results not in my new set?
      instructions:
      - text: Replace resource results of insight {insightKey} in {sourceID} with {resourceResults}.
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
          resourceResults: requestBody.resourceResults
      - text: 'Overwrite affected resources on {insightKey} for source {sourceID}: {resourceResults}.'
        slots:
          insightKey: path.insightKey
          sourceID: path.sourceID
          resourceResults: requestBody.resourceResults
      method: generated
      generated: '2026-10-01'