# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Scope3 Storefront Storefront Ad Server Buyer Routing API
  version: 1.0.0
extends: openapi/scope3-storefront-ad-server-buyer-routing-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: 14
- target: $.paths['/esa/{esaId}/sandbox-account'].get
  update:
    x-apievangelist-phrasing:
      intent: Check ad server sandbox account readiness
      effect: read
      questions:
      - Is the sandbox advertiser account ready for no-spend tests on my ad server source?
      - Can I check sandbox readiness before running buyer-stack tests?
      instructions:
      - text: Check sandbox account readiness for ad server source {esaId}.
        slots:
          esaId: path.esaId
      - text: Show the sandbox account status on source {esaId}.
        slots:
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/sandbox-account/ensure'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or repair the ad server sandbox account
      effect: write
      questions:
      - How do I make sure a sandbox advertiser account exists for no-spend testing?
      - Can a broken sandbox account mapping be repaired automatically?
      instructions:
      - text: Ensure the sandbox account exists on ad server source {esaId}.
        slots:
          esaId: path.esaId
      - text: Create or repair the no-spend sandbox account for source {esaId}.
        slots:
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/advertisers'].get
  update:
    x-apievangelist-phrasing:
      intent: List ad server advertisers for any adapter
      effect: read
      questions:
      - Which advertisers exist in my connected ad server, whatever platform it is?
      - How can I tell if the advertiser roster read was complete?
      instructions:
      - text: List advertisers on ad server source {esaId}.
        slots:
          esaId: path.esaId
      - text: Read up to {limit} advertisers from the ad server behind {esaId}.
        slots:
          limit: query.limit
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/gam/advertisers'].get
  update:
    x-apievangelist-phrasing:
      intent: List cached Google Ad Manager advertisers
      effect: read
      questions:
      - Which Google Ad Manager advertisers are cached for my source?
      - Can I search cached GAM advertisers by name?
      instructions:
      - text: List cached GAM advertisers for source {esaId}.
        slots:
          esaId: path.esaId
      - text: Search cached GAM advertisers on {esaId} for {q}.
        slots:
          esaId: path.esaId
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/gam/advertisers/ensure'].post
  update:
    x-apievangelist-phrasing:
      intent: Find or create a GAM advertiser by name
      effect: write
      questions:
      - How do I create a Google Ad Manager advertiser to route buyers to?
      - Can I dry-run creating a GAM advertiser first?
      instructions:
      - text: Ensure a GAM advertiser named {name} exists on source {esaId}.
        slots:
          name: requestBody.name
          esaId: path.esaId
      - text: Find or create GAM advertiser {name} for {esaId}, dry run {dryRun}.
        slots:
          name: requestBody.name
          esaId: path.esaId
          dryRun: requestBody.dryRun
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/default-advertiser'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the catch-all advertiser for any ad server
      effect: write
      questions:
      - Where do unmatched buyers get routed in my ad server?
      - Can I set a default advertiser without caring which ad server backs the agent?
      instructions:
      - text: Set the default advertiser on source {esaId} to {advertiserId}.
        slots:
          esaId: path.esaId
          advertiserId: requestBody.advertiserId
      - text: Route all unmatched buyers on {esaId} to advertiser {advertiserId}.
        slots:
          esaId: path.esaId
          advertiserId: requestBody.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/gam/default-advertiser'].put
  update:
    x-apievangelist-phrasing:
      intent: Set the default GAM advertiser
      effect: write
      questions:
      - Can I set the Google Ad Manager-specific default advertiser for buyer routing?
      - Is there a GAM-only way to pick the fallback advertiser?
      instructions:
      - text: Set the default GAM advertiser for {esaId} to {gamAdvertiserId}.
        slots:
          esaId: path.esaId
          gamAdvertiserId: requestBody.gamAdvertiserId
      - text: Use GAM advertiser {gamAdvertiserId} as the fallback on GAM source {esaId}.
        slots:
          gamAdvertiserId: requestBody.gamAdvertiserId
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/gam-custom-targeting-keys/ensure'].post
  update:
    x-apievangelist-phrasing:
      intent: Create GAM custom-targeting keys
      effect: write
      questions:
      - How do I add custom-targeting keys in Google Ad Manager through my source?
      - Will existing GAM keys be duplicated if I ensure them again?
      instructions:
      - text: Ensure GAM custom-targeting keys {keys} exist on {esaId}.
        slots:
          keys: requestBody.keys
          esaId: path.esaId
      - text: Create missing custom-targeting keys {keys} in GAM for source {esaId}.
        slots:
          keys: requestBody.keys
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/axe-keys'].put
  update:
    x-apievangelist-phrasing:
      intent: Configure AXE targeting key names
      effect: write
      questions:
      - Which GAM keys carry Scope3 include, exclude and emissions macro targeting?
      - Does the AXE macro key have to be a specific value?
      instructions:
      - text: 'Configure AXE keys on {esaId}: include {axeIncludeKey}, exclude {axeExcludeKey}, macro {axeMacroKey}.'
        slots:
          esaId: path.esaId
          axeIncludeKey: requestBody.axeIncludeKey
          axeExcludeKey: requestBody.axeExcludeKey
          axeMacroKey: requestBody.axeMacroKey
      - text: Set AXE include key {axeIncludeKey}, exclude key {axeExcludeKey} and macro key {axeMacroKey} for source {esaId}.
        slots:
          axeIncludeKey: requestBody.axeIncludeKey
          axeExcludeKey: requestBody.axeExcludeKey
          axeMacroKey: requestBody.axeMacroKey
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/buyer-advertiser-mappings'].get
  update:
    x-apievangelist-phrasing:
      intent: List buyer-to-advertiser routing mappings
      effect: read
      questions:
      - Which buyers are mapped to specific GAM advertisers?
      - Can I look up the routing mapping for one buyer's operator domain?
      instructions:
      - text: List buyer advertiser mappings on {esaId}.
        slots:
          esaId: path.esaId
      - text: Show the mapping for operator domain {operatorDomain} on {esaId}.
        slots:
          operatorDomain: query.operatorDomain
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/buyer-advertiser-mappings'].post
  update:
    x-apievangelist-phrasing:
      intent: Map a buyer to a GAM advertiser
      effect: write
      questions:
      - How do I route a specific buyer to its own GAM advertiser?
      - Can a buyer mapping be scoped to one brand?
      instructions:
      - text: Map buyer {operatorDomain} to GAM advertiser {gamAdvertiserId} on {esaId}.
        slots:
          operatorDomain: requestBody.operatorDomain
          gamAdvertiserId: requestBody.gamAdvertiserId
          esaId: path.esaId
      - text: Route {operatorDomain} brand {brandId} to GAM advertiser {gamAdvertiserId} on source {esaId}.
        slots:
          operatorDomain: requestBody.operatorDomain
          brandId: requestBody.brandId
          gamAdvertiserId: requestBody.gamAdvertiserId
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/buyer-advertiser-mappings/{mappingId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a buyer routing mapping
      effect: destructive
      questions:
      - Can I remove a buyer-specific advertiser mapping?
      - What happens to a buyer once its mapping is deleted?
      instructions:
      - text: Delete buyer mapping {mappingId} on {esaId}.
        slots:
          mappingId: path.mappingId
          esaId: path.esaId
      - text: Remove routing mapping {mappingId} from source {esaId}.
        slots:
          mappingId: path.mappingId
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/buyer-advertiser-mappings/{mappingId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a buyer routing mapping
      effect: write
      questions:
      - Can I point an existing buyer mapping at a different GAM advertiser?
      - How do I change the brand on a buyer mapping?
      instructions:
      - text: Point mapping {mappingId} on {esaId} to GAM advertiser {gamAdvertiserId}.
        slots:
          mappingId: path.mappingId
          esaId: path.esaId
          gamAdvertiserId: requestBody.gamAdvertiserId
      - text: Change the brand of mapping {mappingId} on {esaId} to {brandId}.
        slots:
          mappingId: path.mappingId
          esaId: path.esaId
          brandId: requestBody.brandId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/recent-buyers'].get
  update:
    x-apievangelist-phrasing:
      intent: List recent buyers and how they routed
      effect: read
      questions:
      - Which buyers have hit my ad server source recently?
      - Did recent buyers go to the default advertiser or a specific mapping?
      instructions:
      - text: List recent buyers on {esaId}.
        slots:
          esaId: path.esaId
      - text: Show buyers seen on {esaId} in the last {days} days.
        slots:
          esaId: path.esaId
          days: query.days
      method: generated
      generated: '2026-10-01'