OneTrust · OpenAPI Overlay 1.0.0

API Evangelist conversational phrasing for Data Use Governance - Data Discovery Scan Jobs API

7 actions 7 updates phrasing extends openapi/onetrust-scan-jobs-api-openapi.yml

Generated by API Evangelist Written by API Evangelist tooling for OneTrust's API. It is a proposal applied on top of the contract, not a document OneTrust publishes.

View Overlay File View on GitHub Overlay Specification

What the actions change

x-apievangelist-phrasing

Targets 7

$.info

$.paths['/api/discovery-scan-config/v2/scan-job'].post

$.paths['/api/discovery-scan-config/v2/scan-job/datasource/{dataSourceId}'].get

$.paths['/api/discovery-scan-config/v2/scan-job/{jobId}'].get

$.paths['/api/discovery-scan-config/v2/scan-job/{jobId}/cancel'].patch

$.paths['/api/discovery-scan-config/v2/scanners/{scannerId}/jobs/{jobId}'].get

$.paths['/api/discovery-scan-config/v2/scanners/{scannerId}/jobs/{jobId}/cancel'].patch

OpenAPI Overlay

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Data Use Governance - Data Discovery Scan Jobs API
  version: 1.0.0
extends: openapi/onetrust-scan-jobs-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/discovery-scan-config/v2/scan-job'].post
  update:
    x-apievangelist-phrasing:
      intent: Start a data discovery scan job
      effect: write
      questions:
      - How do I kick off a new discovery scan on a data source?
      - Can I choose the scan, classification and detector profiles for a scan job?
      instructions:
      - text: Start a scan job on data source {dataSourceId}.
        slots:
          dataSourceId: requestBody.dataSourceId
      - text: Scan data source {dataSourceId} using scan profile {scanProfileId} and classification profile {classificationProfileId}.
        slots:
          dataSourceId: requestBody.dataSourceId
          scanProfileId: requestBody.scanProfileId
          classificationProfileId: requestBody.classificationProfileId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/discovery-scan-config/v2/scan-job/datasource/{dataSourceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: List scan jobs for a data source
      effect: read
      questions:
      - What scan jobs have run against a given data source?
      - Can I filter a data source's scan jobs by status or created date range?
      - Which scans on a data source were started manually?
      instructions:
      - text: List scan jobs for data source {dataSourceId}.
        slots:
          dataSourceId: path.dataSourceId
      - text: Show {status} scan jobs on data source {dataSourceId}.
        slots:
          status: query.status
          dataSourceId: path.dataSourceId
      - text: List scans of data source {dataSourceId} created between {createdFrom} and {createdTo}.
        slots:
          dataSourceId: path.dataSourceId
          createdFrom: query.createdFrom
          createdTo: query.createdTo
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/discovery-scan-config/v2/scan-job/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a scan job's status and progress
      effect: read
      questions:
      - How far along is my scan job and has ingestion finished?
      - What scan profile and metadata counts does a scan job report, using just the job ID?
      instructions:
      - text: Show the progress of scan job {jobId}.
        slots:
          jobId: path.jobId
      - text: Get status, timestamps and ingestion state for scan job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/discovery-scan-config/v2/scan-job/{jobId}/cancel'].patch
  update:
    x-apievangelist-phrasing:
      intent: Cancel a scan job by job ID
      effect: destructive
      questions:
      - How do I stop a pending or processing scan job using only its job ID?
      - Which scan job states can't be cancelled anymore?
      instructions:
      - text: Cancel scan job {jobId}.
        slots:
          jobId: path.jobId
      - text: Stop the running scan job {jobId}.
        slots:
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/discovery-scan-config/v2/scanners/{scannerId}/jobs/{jobId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a scan job on a specific scanner
      effect: read
      questions:
      - How do I fetch a scan job through the scanner that ran it?
      - Can I look up a job by scanner ID and job ID together?
      instructions:
      - text: Get job {jobId} from scanner {scannerId}.
        slots:
          jobId: path.jobId
          scannerId: path.scannerId
      - text: Show scanner {scannerId}'s scan job {jobId}.
        slots:
          scannerId: path.scannerId
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/discovery-scan-config/v2/scanners/{scannerId}/jobs/{jobId}/cancel'].patch
  update:
    x-apievangelist-phrasing:
      intent: Cancel a scan job on a specific scanner
      effect: destructive
      questions:
      - How do I cancel a job running on a particular scanner?
      - Can I cancel a scan by giving both the scanner and job IDs?
      instructions:
      - text: Cancel job {jobId} on scanner {scannerId}.
        slots:
          jobId: path.jobId
          scannerId: path.scannerId
      - text: Stop scanner {scannerId}'s job {jobId}.
        slots:
          scannerId: path.scannerId
          jobId: path.jobId
      method: generated
      generated: '2026-09-26'