# 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 - Audit Management Audits API
  version: 1.0.0
extends: openapi/onetrust-audits-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: 7
- target: $.paths['/api/audit-management/v1/audit-scopes/{scopeId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a control from an audit's scope
      effect: destructive
      questions:
      - Can I take a control or control implementation out of an audit's scope?
      - Are findings deleted when a scope item is removed from an audit?
      instructions:
      - text: Delete audit scope {scopeId}.
        slots:
          scopeId: path.scopeId
      - text: Remove scope item {scopeId} from its audit and delete findings {deleteFinding}.
        slots:
          scopeId: path.scopeId
          deleteFinding: query.deleteFinding
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/audit-management/v1/audits'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an audit
      effect: write
      questions:
      - What do I need to set up a new audit against a framework?
      - Can I assign auditors and approvers when creating an audit?
      instructions:
      - text: 'Create audit {header} on {framework} for {orgGroup}: auditors {auditors}, approvers {approvers}, source {auditSourceType}, scopes {scopes}.'
        slots:
          framework: requestBody.framework
          orgGroup: requestBody.orgGroup
          auditors: requestBody.auditors
          approvers: requestBody.approvers
          header: requestBody.header
          auditSourceType: requestBody.auditSourceType
          scopes: requestBody.scopes
      - text: Start a new audit with header {header} against {framework}.
        slots:
          header: requestBody.header
          framework: requestBody.framework
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/audit-management/v1/audits/pages'].post
  update:
    x-apievangelist-phrasing:
      intent: Search and list audits
      effect: read
      questions:
      - Which audits are currently set up, and who are the auditors on each?
      - Can I search audits by keyword and filters?
      instructions:
      - text: List all audits.
      - text: Search audits for {fullText}.
        slots:
          fullText: requestBody.fullText
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/audit-management/v1/audits/{auditId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an audit
      effect: read
      questions:
      - Can I pull up a single audit by its ID?
      - Where do I see one audit's full details?
      instructions:
      - text: Get audit {auditId}.
        slots:
          auditId: path.auditId
      - text: Show details for audit {auditId}.
        slots:
          auditId: path.auditId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/audit-management/v1/audits/{auditId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an audit's auditors and approvers
      effect: write
      questions:
      - Can I change the auditors or approvers on an existing audit?
      - Is it possible to edit an audit's attributes after creation?
      instructions:
      - text: Update audit {auditId} auditors to {auditors}, approvers to {approvers}, header {header}, assignment {auditorAssignmentType}.
        slots:
          auditId: path.auditId
          auditors: requestBody.auditors
          approvers: requestBody.approvers
          header: requestBody.header
          auditorAssignmentType: requestBody.auditorAssignmentType
      - text: Change the approvers on audit {auditId} to {approvers}.
        slots:
          auditId: path.auditId
          approvers: requestBody.approvers
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/audit-management/v1/audits/{auditId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an audit
      effect: destructive
      questions:
      - Is deleting an audit permanent, and what goes with it?
      - Can I keep the findings when an audit is deleted?
      instructions:
      - text: Delete audit {auditId}.
        slots:
          auditId: path.auditId
      - text: Permanently delete audit {auditId}, deleting findings {deleteFinding}.
        slots:
          auditId: path.auditId
          deleteFinding: query.deleteFinding
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/audit-management/v1/audits/{auditId}/reassign-scopes'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an audit's scope
      effect: write
      questions:
      - Can I change which controls are in scope for an existing audit?
      - Is there a way to reassign scopes on an audit?
      instructions:
      - text: Update the scope of audit {auditId}.
        slots:
          auditId: path.auditId
      - text: Reassign the in-scope controls on audit {auditId}.
        slots:
          auditId: path.auditId
      method: generated
      generated: '2026-09-26'