# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Tech Risk & Compliance - IT Risk Management Controls API
  version: 1.0.0
extends: openapi/onetrust-controls-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 6
- target: $.paths['/api/controls/v1/controls'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a control
      effect: write
      questions:
      - How do I add a new control to the Controls Library?
      - Can I assign a framework and category to a control when I create it?
      instructions:
      - text: Create control {identifier} named {name} in org {orgGroupId} with origin {origin}.
        slots:
          identifier: requestBody.identifier
          name: requestBody.name
          orgGroupId: requestBody.orgGroupId
          origin: requestBody.origin
      - text: Add control {identifier} {name} under framework {frameworkName} for org {orgGroupId}, origin {origin}.
        slots:
          identifier: requestBody.identifier
          name: requestBody.name
          frameworkName: requestBody.frameworkName
          orgGroupId: requestBody.orgGroupId
          origin: requestBody.origin
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/controls/v1/controls/pages'].post
  update:
    x-apievangelist-phrasing:
      intent: Search controls
      effect: read
      questions:
      - What controls are in my Controls Library?
      - Can I search controls by keyword and see their framework and category?
      instructions:
      - text: List all controls in the library.
      - text: Search controls for {fullText}.
        slots:
          fullText: requestBody.fullText
      - text: Find controls matching filters {filters}.
        slots:
          filters: requestBody.filters
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/controls/v1/controls/{controlId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a control
      effect: write
      questions:
      - How do I change a control's description or implementation guidance?
      - Can I move an existing control to a different category?
      instructions:
      - text: Update control {controlId} with identifier {identifier}, name {name}, org {orgGroupId}.
        slots:
          controlId: path.controlId
          identifier: requestBody.identifier
          name: requestBody.name
          orgGroupId: requestBody.orgGroupId
      - text: Set implementation guidance on control {controlId} to {implementationGuidance}.
        slots:
          controlId: path.controlId
          implementationGuidance: requestBody.implementationGuidance
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/controls/v1/controls/{controlId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a control
      effect: destructive
      questions:
      - How do I remove a control from the Controls Library?
      - Can I delete a control by its ID?
      instructions:
      - text: Delete control {controlId}.
        slots:
          controlId: path.controlId
      - text: Remove control {controlId} from the library.
        slots:
          controlId: path.controlId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/controls/v2/control-entity-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List control entity source types
      effect: read
      questions:
      - Which entity source types can controls be attached to?
      - What control entity source types are enabled?
      instructions:
      - text: List all control entity source types.
      - text: Show the enabled source types for controls.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/controls/v2/related/control-entity-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List related control entity types
      effect: read
      questions:
      - What entity types can be related to controls?
      - Which related entity types does the controls module support?
      instructions:
      - text: List the related control entity types.
      - text: Show which entity types can be linked as related to controls.
      method: generated
      generated: '2026-09-26'