# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Postman APIs API Comments Secret Scanner API
  version: 1.0.0
extends: openapi/postman-secret-scanner-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['/secret-scanner/detected-secrets'].get
  update:
    x-apievangelist-phrasing:
      intent: List secrets detected in team resources
      effect: read
      questions:
      - Have any API keys or tokens leaked into our collections or environments?
      - Can I list only unresolved detected secrets found since a certain date?
      - Which workspaces have the most exposed secrets?
      instructions:
      - text: List all detected secrets across the team.
      - text: Show detected secrets with status {statuses} in workspaces {workspaceIds}.
        slots:
          statuses: query.statuses
          workspaceIds: query.workspaceIds
      - text: Find {secretTypes} secrets detected since {since}.
        slots:
          secretTypes: query.secretTypes
          since: query.since
      method: generated
      generated: '2026-09-26'
- target: $.paths['/secret-scanner/detected-secrets/{secretId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a detected secret's details
      effect: read
      questions:
      - What type of secret was found and what is its resolution history?
      - Can I see the full record of one detected secret?
      instructions:
      - text: Get detected secret {secretId}.
        slots:
          secretId: path.secretId
      - text: Show the resolution history of detected secret {secretId}.
        slots:
          secretId: path.secretId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/secret-scanner/detected-secrets/{secretId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Resolve a detected secret
      effect: write
      questions:
      - How do I mark a leaked key as revoked after I've rotated it?
      - Can I flag a detected secret as a false positive or accepted risk?
      instructions:
      - text: Resolve detected secret {secretId} as {resolution}.
        slots:
          secretId: path.secretId
          resolution: requestBody.resolution
      - text: Mark secret {secretId} with resolution {resolution}.
        slots:
          secretId: path.secretId
          resolution: requestBody.resolution
      method: generated
      generated: '2026-09-26'
- target: $.paths['/secret-scanner/detected-secrets/{secretId}/locations'].get
  update:
    x-apievangelist-phrasing:
      intent: List where a detected secret appears
      effect: read
      questions:
      - In which collections and environments does a leaked secret appear?
      - How many places does one detected secret show up?
      instructions:
      - text: List the locations of detected secret {secretId}.
        slots:
          secretId: path.secretId
      - text: Show every place secret {secretId} was found.
        slots:
          secretId: path.secretId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/secret-scanner/secret-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List secret types the scanner detects
      effect: read
      questions:
      - What kinds of credentials can the secret scanner detect?
      - Is there a list of supported secret types with descriptions?
      instructions:
      - text: List the secret types the scanner supports.
      - text: Show the names and descriptions of detectable secret types.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/detected-secrets-queries'].post
  update:
    x-apievangelist-phrasing:
      intent: Search secrets found by the Secret Scanner
      effect: read
      questions:
      - Which leaked secrets has the Secret Scanner found across our workspaces?
      - Can I filter detected secrets by type, status or workspace?
      - How do I see only unresolved secrets?
      instructions:
      - text: List all secrets the Secret Scanner has detected.
      - text: Search detected secrets in workspaces {workspaceIds}.
        slots:
          workspaceIds: requestBody.workspaceIds
      - text: Find detected secrets of types {secretTypes} with status {statuses}.
        slots:
          secretTypes: requestBody.secretTypes
          statuses: requestBody.statuses
      method: generated
      generated: '2026-10-01'
- target: $.paths['/detected-secrets/{secretId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Mark a detected secret as resolved
      effect: write
      questions:
      - How do I mark a detected secret as revoked or a false positive?
      - Can I change the resolution status of a leaked secret?
      instructions:
      - text: Set secret {secretId} in workspace {workspaceId} to {resolution}.
        slots:
          secretId: path.secretId
          workspaceId: requestBody.workspaceId
          resolution: requestBody.resolution
      - text: Resolve detected secret {secretId} in {workspaceId} as {resolution}.
        slots:
          secretId: path.secretId
          workspaceId: requestBody.workspaceId
          resolution: requestBody.resolution
      method: generated
      generated: '2026-10-01'
- target: $.paths['/detected-secrets/{secretId}/locations'].get
  update:
    x-apievangelist-phrasing:
      intent: Find where a detected secret appears
      effect: read
      questions:
      - Where exactly was this secret found in the workspace?
      - Can I narrow a secret's locations to one resource type?
      instructions:
      - text: Show where secret {secretId} was found in workspace {workspaceId}.
        slots:
          secretId: path.secretId
          workspaceId: query.workspaceId
      - text: List locations of secret {secretId} in {workspaceId} within {resourceType} resources.
        slots:
          secretId: path.secretId
          workspaceId: query.workspaceId
          resourceType: query.resourceType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/secret-types'].get
  update:
    x-apievangelist-phrasing:
      intent: List secret types the scanner detects
      effect: read
      questions:
      - What kinds of secrets can the Secret Scanner detect?
      - Where do I get secret type IDs to filter detected secrets?
      instructions:
      - text: Get the secret type metadata, with type IDs, from the Secret Scanner secret-types endpoint.
      - text: Show secret type IDs I can use in detected-secret searches.
      method: generated
      generated: '2026-10-01'