API Evangelist conversational phrasing for Perigon Source Groups 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 Source Groups API
  version: 1.0.0
extends: openapi/perigon-source-groups-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/sourceGroups'].get
  update:
    x-apievangelist-phrasing:
      intent: List source groups
      effect: read
      questions:
      - Which source groups can I use, including public ones?
      - Can I find source groups that contain a particular domain?
      instructions:
      - text: List my source groups sorted by {sortBy} {sortOrder}.
        slots:
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      - text: Show source groups that include domain {domain}, sorted by {sortBy} {sortOrder}.
        slots:
          domain: query.domain
          sortBy: query.sortBy
          sortOrder: query.sortOrder
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/sourceGroups'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a source group of domains
      effect: write
      questions:
      - How do I bundle a set of news domains into my own source group?
      - Can I give a custom source group a display name and description?
      instructions:
      - text: Create a source group named {name} with domains {domains}.
        slots:
          name: requestBody.name
          domains: requestBody.domains
      - text: Make a new source group {name} described as {description} covering {domains}.
        slots:
          name: requestBody.name
          description: requestBody.description
          domains: requestBody.domains
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/sourceGroups/resolve'].get
  update:
    x-apievangelist-phrasing:
      intent: Resolve source group names
      effect: read
      questions:
      - If my private source group shares a name with a public one, which does a name lookup return?
      - Can I turn source group names into their full definitions in one call?
      instructions:
      - text: Resolve the source group names {name}.
        slots:
          name: query.name
      - text: Look up which source group the name {name} maps to for my organization.
        slots:
          name: query.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/sourceGroups/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a source group by ID
      effect: read
      questions:
      - What domains are in one of my source groups?
      - Can I fetch a single source group using its ID?
      instructions:
      - text: Show source group {id}.
        slots:
          id: path.id
      - text: List the domains inside source group {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/sourceGroups/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a source group
      effect: destructive
      questions:
      - How do I remove a source group my organization owns?
      - Can I delete a custom source group I no longer use?
      instructions:
      - text: Delete source group {id}.
        slots:
          id: path.id
      - text: Remove my source group {id} permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/v1/api/sourceGroups/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a source group
      effect: write
      questions:
      - Can I add or change the domains in an existing source group?
      - Is it possible to rename a source group I already created?
      instructions:
      - text: Replace the domains in source group {id} with {domains}.
        slots:
          id: path.id
          domains: requestBody.domains
      - text: Rename source group {id} to {displayName}.
        slots:
          id: path.id
          displayName: requestBody.displayName
      method: generated
      generated: '2026-10-01'