# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Scope3 Buyer Property Lists API
  version: 1.0.0
extends: openapi/scope3-property-lists-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['/advertisers/{advertiserId}/property-lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List an advertiser's property lists
      effect: read
      questions:
      - Which include and exclude domain lists does my advertiser have?
      - Can I list only my exclude lists?
      instructions:
      - text: List property lists for advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      - text: Show {purpose} property lists for advertiser {advertiserId}.
        slots:
          purpose: query.purpose
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/property-lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an include or exclude domain list
      effect: write
      questions:
      - How do I build a blocklist of publisher domains for an advertiser?
      - What happens to domains that can't be resolved when I create a list?
      instructions:
      - text: Create a {purpose} list named {name} for advertiser {advertiserId} with domains {domains}.
        slots:
          purpose: requestBody.purpose
          name: requestBody.name
          advertiserId: path.advertiserId
          domains: requestBody.domains
      - text: Make an exclude property list {name} of purpose {purpose} under advertiser {advertiserId}.
        slots:
          name: requestBody.name
          purpose: requestBody.purpose
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/property-lists/{listId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a property list
      effect: read
      questions:
      - Which domains are on one of my property lists?
      - Can I see the resolved identifiers for a list?
      instructions:
      - text: Get property list {listId} for advertiser {advertiserId}.
        slots:
          listId: path.listId
          advertiserId: path.advertiserId
      - text: Show the domains on list {listId} of advertiser {advertiserId}.
        slots:
          listId: path.listId
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/property-lists/{listId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rename or replace domains on a property list
      effect: write
      questions:
      - Can I replace all the domains on an existing property list?
      - How do I rename a property list?
      instructions:
      - text: Replace the domains on list {listId} of advertiser {advertiserId} with {domains}.
        slots:
          listId: path.listId
          advertiserId: path.advertiserId
          domains: requestBody.domains
      - text: Rename property list {listId} of advertiser {advertiserId} to {name}.
        slots:
          listId: path.listId
          advertiserId: path.advertiserId
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/property-lists/{listId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive a property list
      effect: destructive
      questions:
      - Does deleting a property list unlink it from targeting?
      - Can I retire a domain list I no longer use?
      instructions:
      - text: Delete property list {listId} from advertiser {advertiserId}.
        slots:
          listId: path.listId
          advertiserId: path.advertiserId
      - text: Archive list {listId} of advertiser {advertiserId}.
        slots:
          listId: path.listId
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/campaigns/{campaignId}/property-lists'].get
  update:
    x-apievangelist-phrasing:
      intent: See which property lists apply to a campaign
      effect: read
      questions:
      - Which domain lists constrain where my campaign can deliver?
      - Are advertiser-level lists applied to a campaign too?
      instructions:
      - text: Get the property lists applying to campaign {campaignId}.
        slots:
          campaignId: path.campaignId
      - text: Show the include and exclude lists on campaign {campaignId}.
        slots:
          campaignId: path.campaignId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/campaigns/{campaignId}/property-lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Push an include list to a running campaign
      effect: write
      questions:
      - Can I apply a new include list to media buys that are already running?
      - What kind of property list can be attached to a live campaign?
      instructions:
      - text: Attach property list {propertyListId} to campaign {campaignId}.
        slots:
          propertyListId: requestBody.propertyListId
          campaignId: path.campaignId
      - text: Push include list {propertyListId} to all active media buys of campaign {campaignId}.
        slots:
          propertyListId: requestBody.propertyListId
          campaignId: path.campaignId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/property-lists/check'].post
  update:
    x-apievangelist-phrasing:
      intent: Check domains against the community registry
      effect: read
      questions:
      - Which of my domains should be removed or reviewed according to the registry?
      - Can I vet a domain list before using it?
      instructions:
      - text: Check domains {domains} against the registry.
        slots:
          domains: requestBody.domains
      - text: Audit identifiers {identifiers} for remove, modify or assess flags.
        slots:
          identifiers: requestBody.identifiers
      method: generated
      generated: '2026-10-01'
- target: $.paths['/property-lists/reports/{reportId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a stored domain check report
      effect: read
      questions:
      - Can I retrieve a property list check report I ran earlier?
      - How long are domain check reports kept?
      instructions:
      - text: Get property list check report {reportId}.
        slots:
          reportId: path.reportId
      - text: Show results of domain check {reportId}.
        slots:
          reportId: path.reportId
      method: generated
      generated: '2026-10-01'