# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Vulnerability Management Shared Collections API
  version: 1.0.0
extends: openapi/tenable-shared-collections-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: 10
- target: $.paths['/shared-collections'].get
  update:
    x-apievangelist-phrasing:
      intent: List shared collections
      effect: read
      questions:
      - Which shared scan collections do I have access to?
      - Where can I see every shared collection visible to my user?
      instructions:
      - text: List the shared collections I can access.
      - text: Show all shared scan collections.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shared-collections'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a shared collection
      effect: write
      questions:
      - How do I create a shared collection to group scans for other users?
      - Is there a maximum number of shared collections I can create?
      - Can I set who has access when creating a shared collection?
      instructions:
      - text: Create a shared collection named {name} with access list {acl}.
        slots:
          name: requestBody.name
          acl: requestBody.acl
      - text: Create shared collection {name} described as {description} and shared with {acl}.
        slots:
          name: requestBody.name
          description: requestBody.description
          acl: requestBody.acl
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shared-collections/{shared_collection_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shared collection by ID
      effect: read
      questions:
      - What are the details and permissions of one shared collection?
      - Who owns a particular shared collection?
      instructions:
      - text: Get details for shared collection {shared_collection_id}.
        slots:
          shared_collection_id: path.shared_collection_id
      - text: Show the access list of shared collection {shared_collection_id}.
        slots:
          shared_collection_id: path.shared_collection_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shared-collections/{shared_collection_id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a shared collection
      effect: write
      questions:
      - Can I rename a shared collection or change who it is shared with?
      - Who is allowed to update a shared collection?
      instructions:
      - text: Rename shared collection {shared_collection_id} to {name} with access list {acl}.
        slots:
          shared_collection_id: path.shared_collection_id
          name: requestBody.name
          acl: requestBody.acl
      - text: Update the description of shared collection {shared_collection_id} to {description}, keeping name {name} and access {acl}.
        slots:
          shared_collection_id: path.shared_collection_id
          description: requestBody.description
          name: requestBody.name
          acl: requestBody.acl
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shared-collections/{shared_collection_id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a shared collection
      effect: destructive
      questions:
      - How do I delete a shared collection I no longer use?
      - Does deleting a shared collection run as an asynchronous job?
      instructions:
      - text: Delete shared collection {shared_collection_id}.
        slots:
          shared_collection_id: path.shared_collection_id
      - text: Remove the shared collection {shared_collection_id} for everyone.
        slots:
          shared_collection_id: path.shared_collection_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shared-collections/_byName'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up a shared collection by name
      effect: read
      questions:
      - Can I find a shared collection if I only know its name?
      - Is there a way to fetch a shared collection's details without its ID?
      instructions:
      - text: Look up the shared collection named {name}.
        slots:
          name: requestBody.name
      - text: Find shared collection details for the name {name}.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shared-collections/request-status/{request_status_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a shared collection job's status
      effect: read
      questions:
      - Did my shared collection create, update or delete job finish?
      - How can I track an asynchronous shared collection request?
      instructions:
      - text: Check the status of shared collection job {request_status_id}.
        slots:
          request_status_id: path.request_status_id
      - text: Tell me if shared collection request {request_status_id} has completed.
        slots:
          request_status_id: path.request_status_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shared-collections/{shared_collection_id}/scan-configs'].get
  update:
    x-apievangelist-phrasing:
      intent: List scan configs in a shared collection
      effect: read
      questions:
      - Which scan configurations are inside a shared collection?
      - Can I page through the scans grouped in one shared collection?
      instructions:
      - text: List scan configs in shared collection {shared_collection_id}.
        slots:
          shared_collection_id: path.shared_collection_id
      - text: Show {limit} scan configurations from shared collection {shared_collection_id} sorted by {sort}.
        slots:
          limit: query.limit
          shared_collection_id: path.shared_collection_id
          sort: query.sort
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shared-collections/{shared_collection_id}/scan-configs'].post
  update:
    x-apievangelist-phrasing:
      intent: Add scan configs to a shared collection
      effect: write
      questions:
      - How do I add scans to an existing shared collection?
      - Can I put several scan configurations into a shared collection at once?
      instructions:
      - text: Add scan configs {scan_configs} to shared collection {shared_collection_id}.
        slots:
          scan_configs: requestBody.scan_configs
          shared_collection_id: path.shared_collection_id
      - text: Put scans {scan_configs} into collection {shared_collection_id}.
        slots:
          scan_configs: requestBody.scan_configs
          shared_collection_id: path.shared_collection_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/shared-collections/{shared_collection_id}/scan-configs'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove scan configs from a shared collection
      effect: destructive
      questions:
      - Can I take scans out of a shared collection without deleting the collection?
      - How do I remove specific scan configurations from a shared collection?
      instructions:
      - text: Remove scan configs {scan_configs} from shared collection {shared_collection_id}.
        slots:
          scan_configs: requestBody.scan_configs
          shared_collection_id: path.shared_collection_id
      - text: Take scans {scan_configs} out of collection {shared_collection_id}.
        slots:
          scan_configs: requestBody.scan_configs
          shared_collection_id: path.shared_collection_id
      method: generated
      generated: '2026-10-01'