# 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 Advertisers API
  version: 1.0.0
extends: openapi/scope3-advertisers-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: 22
- target: $.paths['/advertisers'].get
  update:
    x-apievangelist-phrasing:
      intent: List advertisers
      effect: read
      questions:
      - Which advertisers do I have set up in Scope3?
      - Can I filter my advertiser list to only sandbox advertisers?
      - Is there a way to find an advertiser by name along with its brand details?
      instructions:
      - text: List all my active advertisers.
      - text: Find advertisers whose name matches {name}.
        slots:
          name: query.name
      - text: List advertisers with status {status}, {limit} per page.
        slots:
          status: query.status
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an advertiser
      effect: write
      questions:
      - How do I set up a new advertiser before creating campaigns?
      - What do I need to provide to create an advertiser, like brand and currency?
      - Can I create an advertiser as a sandbox for testing?
      instructions:
      - text: Create an advertiser named {name} for brand {brand} billed in {primaryCurrency}.
        slots:
          name: requestBody.name
          brand: requestBody.brand
          primaryCurrency: requestBody.primaryCurrency
      - text: Set up a new sandbox advertiser called {name} with brand {brand} in {primaryCurrency}.
        slots:
          name: requestBody.name
          brand: requestBody.brand
          primaryCurrency: requestBody.primaryCurrency
      method: generated
      generated: '2026-10-01'
- target: $.paths['/all-advertisers-home'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the all-advertisers landing overview
      effect: read
      questions:
      - Can I get a portfolio summary across all my advertisers with campaign counts?
      - Which of my advertisers have a resumable draft waiting?
      instructions:
      - text: Show me the all-advertisers home view with portfolio totals.
      - text: Pull the landing overview of every advertiser and its campaign count.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an advertiser's details
      effect: read
      questions:
      - What brand details and ADCP manifest are stored for one of my advertisers?
      - Can I look up a single advertiser by its ID?
      instructions:
      - text: Get advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      - text: Show the full brand details for advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an advertiser
      effect: write
      questions:
      - Can I change an existing advertiser's frequency caps or UTM settings?
      - How do I rename an advertiser or change its primary currency?
      instructions:
      - text: Rename advertiser {advertiserId} to {name}.
        slots:
          advertiserId: path.advertiserId
          name: requestBody.name
      - text: Change the primary currency of advertiser {advertiserId} to {primaryCurrency}.
        slots:
          advertiserId: path.advertiserId
          primaryCurrency: requestBody.primaryCurrency
      - text: Update the frequency caps on advertiser {advertiserId} to {frequencyCaps}.
        slots:
          advertiserId: path.advertiserId
          frequencyCaps: requestBody.frequencyCaps
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive an advertiser
      effect: destructive
      questions:
      - What happens when I delete an advertiser, is it archived?
      - Can I remove an advertiser I no longer run campaigns for?
      instructions:
      - text: Delete advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      - text: Archive the advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/restore'].post
  update:
    x-apievangelist-phrasing:
      intent: Restore an archived advertiser
      effect: write
      questions:
      - Can I bring back an advertiser I archived by mistake?
      - Is a deleted advertiser recoverable?
      instructions:
      - text: Restore archived advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      - text: Make deleted advertiser {advertiserId} active again.
        slots:
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/data-delivery-credentials/{name}/validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Revalidate a data delivery credential
      effect: write
      questions:
      - After fixing bucket access, how do I re-test my data delivery destination?
      - Why is my object-storage data delivery credential marked FAILED and can I recheck it?
      instructions:
      - text: Revalidate data delivery credential {name} on advertiser {advertiserId}.
        slots:
          name: path.name
          advertiserId: path.advertiserId
      - text: Re-run the destination probe for credential {name} of advertiser {advertiserId}.
        slots:
          name: path.name
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/accounts'].get
  update:
    x-apievangelist-phrasing:
      intent: List an advertiser's linked accounts
      effect: read
      questions:
      - Which sales-agent accounts are already linked to my advertiser?
      - Can I see only the linked accounts from one sales agent?
      instructions:
      - text: List the accounts linked to advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      - text: Show accounts linked to advertiser {advertiserId} from storefront {storefrontId}.
        slots:
          advertiserId: path.advertiserId
          storefrontId: query.storefrontId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/accounts'].post
  update:
    x-apievangelist-phrasing:
      intent: Link a partner account to an advertiser
      effect: write
      questions:
      - How do I connect a seller account I discovered to my advertiser?
      - Can I choose the billing type when linking a partner account?
      instructions:
      - text: Link account {accountId} from source {sourceId} on storefront {storefrontId} to advertiser {advertiserId}.
        slots:
          accountId: requestBody.accountId
          sourceId: requestBody.sourceId
          storefrontId: requestBody.storefrontId
          advertiserId: path.advertiserId
      - text: Assign partner account {accountId} to advertiser {advertiserId} via storefront {storefrontId} and source {sourceId}.
        slots:
          accountId: requestBody.accountId
          advertiserId: path.advertiserId
          storefrontId: requestBody.storefrontId
          sourceId: requestBody.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/accounts/{accountId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one linked account on an advertiser
      effect: read
      questions:
      - Can I check the details of a single sales-agent account linked to an advertiser?
      - What is stored for one particular linked account on my advertiser?
      instructions:
      - text: Get linked account {accountId} on advertiser {advertiserId}.
        slots:
          accountId: path.accountId
          advertiserId: path.advertiserId
      - text: Show me account {accountId} as linked to advertiser {advertiserId}.
        slots:
          accountId: path.accountId
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/accounts/available'].get
  update:
    x-apievangelist-phrasing:
      intent: Discover accounts available to link
      effect: read
      questions:
      - Which seller accounts could I still link to my advertiser from a sales agent?
      - Can I force a fresh lookup of linkable accounts instead of cached results?
      instructions:
      - text: Find accounts available to link to advertiser {advertiserId} from storefront {storefrontId} source {sourceId}.
        slots:
          advertiserId: path.advertiserId
          storefrontId: query.storefrontId
          sourceId: query.sourceId
      - text: Refresh and list linkable accounts for advertiser {advertiserId} from source {sourceId} on storefront {storefrontId}.
        slots:
          advertiserId: path.advertiserId
          sourceId: query.sourceId
          storefrontId: query.storefrontId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/accounts/{linkId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Unlink a partner account from an advertiser
      effect: destructive
      questions:
      - What happens to buys if I unmap a partner account from my advertiser?
      - Can I disconnect a linked seller account but keep its history?
      instructions:
      - text: Unlink account mapping {linkId} from advertiser {advertiserId}.
        slots:
          linkId: path.linkId
          advertiserId: path.advertiserId
      - text: Remove partner account link {linkId} on advertiser {advertiserId}.
        slots:
          linkId: path.linkId
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/accounts/{linkId}/reporting-bucket'].put
  update:
    x-apievangelist-phrasing:
      intent: Set a linked account's reporting bucket
      effect: write
      questions:
      - Can I configure an offline reporting bucket on a linked partner account?
      - How do I clear the reporting bucket on an account link?
      instructions:
      - text: Set the reporting bucket on link {linkId} of advertiser {advertiserId} to {reporting_bucket}.
        slots:
          linkId: path.linkId
          advertiserId: path.advertiserId
          reporting_bucket: requestBody.reporting_bucket
      - text: Clear the reporting bucket for account link {linkId} on advertiser {advertiserId} by setting it to {reporting_bucket}.
        slots:
          linkId: path.linkId
          advertiserId: path.advertiserId
          reporting_bucket: requestBody.reporting_bucket
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/catalogs'].get
  update:
    x-apievangelist-phrasing:
      intent: List an advertiser's synced catalogs
      effect: read
      questions:
      - Which product catalogs have been synced for my advertiser?
      - Can I filter synced catalogs by type?
      instructions:
      - text: List catalogs synced for advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      - text: Show {type} catalogs for advertiser {advertiserId}.
        slots:
          type: query.type
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/catalogs/sync'].post
  update:
    x-apievangelist-phrasing:
      intent: Sync catalogs and items to an advertiser
      effect: write
      questions:
      - How do I push my product catalog feed into an advertiser?
      - Can I dry-run a catalog sync before applying it?
      - Will a catalog sync delete catalogs I left out?
      instructions:
      - text: Sync catalogs {catalogs} for account {account} to advertiser {advertiserId}.
        slots:
          catalogs: requestBody.catalogs
          account: requestBody.account
          advertiserId: path.advertiserId
      - text: Dry-run syncing catalogs {catalogs} into advertiser {advertiserId} for account {account}.
        slots:
          catalogs: requestBody.catalogs
          advertiserId: path.advertiserId
          account: requestBody.account
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/catalogs/{catalogId}/transform'].put
  update:
    x-apievangelist-phrasing:
      intent: Save a catalog transform
      effect: write
      questions:
      - How do I define the rules that map catalog items into campaign groups and budget hints?
      - Can I save a named transform for a catalog?
      instructions:
      - text: Save transform {transform} for catalog {catalogId} on advertiser {advertiserId}.
        slots:
          transform: requestBody.transform
          catalogId: path.catalogId
          advertiserId: path.advertiserId
      - text: Set the active transform of catalog {catalogId} for advertiser {advertiserId} to {transform}, named {name}.
        slots:
          catalogId: path.catalogId
          advertiserId: path.advertiserId
          transform: requestBody.transform
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/catalogs/{catalogId}/activation-plan/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a catalog activation plan
      effect: write
      questions:
      - Can I see what campaigns a catalog would produce before launching anything?
      - Is it possible to save the activation plan preview for later execution?
      instructions:
      - text: Preview the activation plan for catalog {catalogId} on advertiser {advertiserId}.
        slots:
          catalogId: path.catalogId
          advertiserId: path.advertiserId
      - text: Build and save an activation plan preview for catalog {catalogId} of advertiser {advertiserId}.
        slots:
          catalogId: path.catalogId
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/catalogs/{catalogId}/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh a URL-backed catalog feed
      effect: write
      questions:
      - How do I pull the latest version of my URL-based catalog feed?
      - Can a catalog refresh also run the activation plan automatically?
      instructions:
      - text: Refresh catalog {catalogId} for advertiser {advertiserId}.
        slots:
          catalogId: path.catalogId
          advertiserId: path.advertiserId
      - text: 'Refetch catalog {catalogId} of advertiser {advertiserId} and execute activation: {executeActivation}.'
        slots:
          catalogId: path.catalogId
          advertiserId: path.advertiserId
          executeActivation: requestBody.executeActivation
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/catalogs/{catalogId}/activation-plan/execute'].post
  update:
    x-apievangelist-phrasing:
      intent: Execute a catalog activation plan
      effect: write
      questions:
      - What does executing a catalog activation plan create downstream?
      - Can I run a saved activation plan by its plan ID?
      instructions:
      - text: Execute activation plan {planId} for catalog {catalogId} on advertiser {advertiserId}.
        slots:
          planId: requestBody.planId
          catalogId: path.catalogId
          advertiserId: path.advertiserId
      - text: Launch the catalog activation for catalog {catalogId} of advertiser {advertiserId}.
        slots:
          catalogId: path.catalogId
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{accountId}/audiences/sync'].post
  update:
    x-apievangelist-phrasing:
      intent: Sync first-party CRM audiences
      effect: write
      questions:
      - How do I upload my first-party CRM audiences?
      - Is audience syncing asynchronous, and can I get notified when it finishes?
      instructions:
      - text: Sync audiences {audiences} to my account.
        slots:
          audiences: requestBody.audiences
      - text: 'Sync CRM audiences {audiences} and delete missing ones: {deleteMissing}.'
        slots:
          audiences: requestBody.audiences
          deleteMissing: requestBody.deleteMissing
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{accountId}/audiences'].get
  update:
    x-apievangelist-phrasing:
      intent: List stored audiences
      effect: read
      questions:
      - Which first-party audiences are stored on my account?
      - Can I page through my audience metadata?
      instructions:
      - text: List my stored audiences.
      - text: Show {take} audiences starting after {skip}.
        slots:
          take: query.take
          skip: query.skip
      method: generated
      generated: '2026-10-01'