API Evangelist conversational phrasing for Perigon Watchlists API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Perigon Watchlists API
  version: 1.0.0
extends: openapi/perigon-watchlists-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: 6
- target: $.paths['/v1/api/watchlists'].get
  update:
    x-apievangelist-phrasing:
      intent: List watchlists
      effect: read
      questions:
      - Which watchlists of people and companies can I use?
      - Can I filter my watchlists by name?
      instructions:
      - text: List my watchlists sorted by {sortBy} {sortOrder}.
        slots:
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      - text: Show watchlists matching {name}, ordered by {sortBy} {sortOrder}.
        slots:
          name: query.name
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/watchlists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a watchlist of people and companies
      effect: write
      questions:
      - How do I build a watchlist of executives and companies to track?
      - How many people and companies can a single watchlist hold?
      instructions:
      - text: Create a watchlist named {name} with people {people} and companies {companies}.
        slots:
          name: requestBody.name
          people: requestBody.people
          companies: requestBody.companies
      - text: Make a private watchlist {name} tracking {companies} and {people}, visibility {visible}.
        slots:
          name: requestBody.name
          companies: requestBody.companies
          people: requestBody.people
          visible: requestBody.visible
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/watchlists/resolve'].get
  update:
    x-apievangelist-phrasing:
      intent: Resolve watchlist names
      effect: read
      questions:
      - If a private watchlist and a public one share a name, which does a lookup by name return?
      - Can I resolve several watchlist names at once?
      instructions:
      - text: Resolve the watchlist names {name}.
        slots:
          name: query.name
      - text: Work out which watchlist the name {name} refers to for my organization.
        slots:
          name: query.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/watchlists/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a watchlist by ID
      effect: read
      questions:
      - Who is on a particular watchlist?
      - Can I fetch one watchlist by its ID?
      instructions:
      - text: Show watchlist {id}.
        slots:
          id: path.id
      - text: List the people and companies on watchlist {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/watchlists/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a watchlist
      effect: destructive
      questions:
      - Why can't I delete a watchlist that active monitors use?
      - How do I remove a watchlist I own?
      instructions:
      - text: Delete watchlist {id}.
        slots:
          id: path.id
      - text: Remove watchlist {id} from my organization.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/watchlists/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a watchlist
      effect: write
      questions:
      - Can I add companies to a watchlist I already made?
      - Is it possible to make an existing watchlist public or private?
      instructions:
      - text: Set the companies on watchlist {id} to {companies}.
        slots:
          id: path.id
          companies: requestBody.companies
      - text: Change watchlist {id} visibility to {visible}.
        slots:
          id: path.id
          visible: requestBody.visible
      - text: Update the people on watchlist {id} to {people}.
        slots:
          id: path.id
          people: requestBody.people
      method: generated
      generated: '2026-10-01'