# 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 Storefronts API
  version: 1.0.0
extends: openapi/scope3-storefronts-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: 19
- target: $.paths['/storefronts'].get
  update:
    x-apievangelist-phrasing:
      intent: List storefronts I can buy from
      effect: read
      questions:
      - Which storefronts are available for me to buy media from?
      - Can I filter storefronts by channel, region or publisher domain?
      instructions:
      - text: List the storefronts available to me.
      - text: List {channel} storefronts in {region}.
        slots:
          channel: query.channel
          region: query.region
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefronts/{storefrontId}'].get
  update:
    x-apievangelist-phrasing:
      intent: View a storefront and my connection status
      effect: read
      questions:
      - Am I connected to a particular storefront?
      - Can I see one storefront's details by id?
      instructions:
      - text: Show storefront {storefront_id}.
        slots:
          storefront_id: path.storefrontId
      - text: Check my connection status for storefront {storefront_id}.
        slots:
          storefront_id: path.storefrontId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefronts/{storefrontId}/capabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: Diagnose a storefront's source capabilities
      effect: read
      questions:
      - What can each inventory source in a storefront actually do?
      - Why might a storefront source not support what I need?
      instructions:
      - text: Show capability diagnostics for storefront {storefront_id}.
        slots:
          storefront_id: path.storefrontId
      - text: Inspect what each source in storefront {storefront_id} supports.
        slots:
          storefront_id: path.storefrontId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront-connections'].get
  update:
    x-apievangelist-phrasing:
      intent: List my storefront connections and sharing settings
      effect: read
      questions:
      - Which storefronts have I connected and are buying, events and feeds turned on?
      - Is my delegated auth to an adapter storefront still valid?
      instructions:
      - text: List my storefront connections.
      - text: Show my connection and sharing settings for storefront {storefront_id}.
        slots:
          storefront_id: query.storefrontId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront-connection-account-mappings'].get
  update:
    x-apievangelist-phrasing:
      intent: List external accounts and their advertiser mappings
      effect: read
      questions:
      - Which external ad accounts are mapped to which of my advertisers across integrations?
      - Can I find external accounts that aren't mapped to an advertiser yet?
      instructions:
      - text: List external account mappings across all my integrations.
      - text: Show external accounts with mapping status {mapping_status} for provider {provider}.
        slots:
          mapping_status: query.mappingStatus
          provider: query.provider
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront-connections/{connectionId}/accounts'].get
  update:
    x-apievangelist-phrasing:
      intent: List external accounts found on one connection
      effect: read
      questions:
      - What external accounts were discovered on a specific integration connection?
      - Which ad accounts came through after I connected a platform?
      instructions:
      - text: List external accounts discovered on connection {connection_id}.
        slots:
          connection_id: path.connectionId
      - text: Show the accounts and advertiser mappings for connection {connection_id}.
        slots:
          connection_id: path.connectionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront-connections/{connectionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Disconnect from an adapter storefront
      effect: destructive
      questions:
      - How do I disconnect an integration to an adapter storefront?
      - Is removing a storefront connection an archive or a hard delete?
      instructions:
      - text: Remove storefront connection {connection_id}.
        slots:
          connection_id: path.connectionId
      - text: Archive my integration connection {connection_id}.
        slots:
          connection_id: path.connectionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront-connections/{connectionId}/accounts/{accountId}/select'].patch
  update:
    x-apievangelist-phrasing:
      intent: Choose which external account a connection uses
      effect: write
      questions:
      - My connection found several ad accounts — how do I pick the one to use?
      - Can I switch the selected external account on an integration?
      instructions:
      - text: Select account {account_id} on connection {connection_id}.
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
      - text: Use external account {account_id} as the active one for connection {connection_id}.
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront-connections/{connectionId}/accounts/{accountId}/advertiser'].post
  update:
    x-apievangelist-phrasing:
      intent: Map an external account to an advertiser
      effect: write
      questions:
      - How do I link an external ad account to one of my advertisers?
      - Can I scope an account mapping to a specific source?
      instructions:
      - text: Map external account {account_id} on connection {connection_id} to advertiser {advertiser_id}.
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
          advertiser_id: requestBody.advertiserId
      - text: Link account {account_id} (connection {connection_id}) to advertiser {advertiser_id} for source {source_id}.
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
          advertiser_id: requestBody.advertiserId
          source_id: requestBody.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscribe'].post
  update:
    x-apievangelist-phrasing:
      intent: Mirror an account's upstream campaigns
      effect: write
      questions:
      - Can I bring the campaigns already running in an external ad account into view here?
      - How much history comes over when I subscribe an account to directed campaigns?
      instructions:
      - text: Subscribe account {account_id} on connection {connection_id} to directed campaigns for advertiser {advertiser_id}.
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
          advertiser_id: requestBody.advertiserId
      - text: Start mirroring upstream campaigns from account {account_id} (connection {connection_id}) into advertiser {advertiser_id}.
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
          advertiser_id: requestBody.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscription'].get
  update:
    x-apievangelist-phrasing:
      intent: Check directed-campaign sync health
      effect: read
      questions:
      - When did my mirrored campaigns last sync, and did it succeed?
      - How fresh is the directed-campaign data for a connected account?
      instructions:
      - text: Check directed-campaign subscription health for account {account_id} on connection {connection_id}.
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
      - text: Show the latest campaign mirror sync for account {account_id}, connection {connection_id}.
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront-connections/{connectionId}/accounts/{accountId}/directed-campaigns/subscription'].delete
  update:
    x-apievangelist-phrasing:
      intent: Stop mirroring an account's campaigns
      effect: destructive
      questions:
      - How do I stop mirroring campaigns from an external account?
      - What happens to the mirrored directed campaigns when I unsubscribe?
      instructions:
      - text: Unsubscribe account {account_id} on connection {connection_id} from directed campaigns.
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
      - text: Retire the campaign mirrors for account {account_id} (connection {connection_id}).
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront-connections/{connectionId}/accounts/{accountId}/presences'].get
  update:
    x-apievangelist-phrasing:
      intent: List audiences and event sources on a connected account
      effect: read
      questions:
      - Which audiences and event sources exist on a connected ad account?
      - Can I see sync status for audiences I pushed to an external account?
      instructions:
      - text: List audiences and event sources on account {account_id}, connection {connection_id}.
        slots:
          account_id: path.accountId
          connection_id: path.connectionId
      - text: Show {object_type} presences for account {account_id} on connection {connection_id}, including retired ones.
        slots:
          object_type: query.objectType
          account_id: path.accountId
          connection_id: path.connectionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefronts/{storefrontId}/connection-policy'].patch
  update:
    x-apievangelist-phrasing:
      intent: Turn buying, events or feed sharing on or off
      effect: write
      questions:
      - Can I stop buying from a storefront without disconnecting it?
      - How do I turn off sending conversion events to a storefront?
      instructions:
      - text: Turn buying from storefront {storefront_id} to {buy_enabled}.
        slots:
          storefront_id: path.storefrontId
          buy_enabled: requestBody.buyEnabled
      - text: Set event sharing to {events_enabled} and feed sharing to {feeds_enabled} for storefront {storefront_id}.
        slots:
          events_enabled: requestBody.eventsEnabled
          feeds_enabled: requestBody.feedsEnabled
          storefront_id: path.storefrontId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefronts/{storefrontId}/connection'].post
  update:
    x-apievangelist-phrasing:
      intent: Connect to an adapter storefront
      effect: write
      questions:
      - How do I connect my ad platform account so I can buy through it?
      - What do I do with the connection URL returned when connecting a storefront?
      instructions:
      - text: Connect me to storefront {storefront_id}.
        slots:
          storefront_id: path.storefrontId
      - text: Resume my integration with storefront {storefront_id} and give me the handoff link.
        slots:
          storefront_id: path.storefrontId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefronts/credentials'].get
  update:
    x-apievangelist-phrasing:
      intent: List my registered storefront credentials
      effect: read
      questions:
      - Which credentials have I registered for storefront sources?
      - Which inventory sources does each of my credentials unlock?
      instructions:
      - text: List my registered storefront credentials.
      - text: Show which sources each of my credentials gives access to.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefronts/{storefrontId}/sources/{sourceId}/credentials'].post
  update:
    x-apievangelist-phrasing:
      intent: Register credentials for an inventory source
      effect: write
      questions:
      - How do I give my account credentials to an inventory source inside a storefront?
      - Can I register a marketplace account for a storefront source?
      instructions:
      - text: Register account {account_identifier} for source {source_id} in storefront {storefront_id}.
        slots:
          account_identifier: requestBody.accountIdentifier
          source_id: path.sourceId
          storefront_id: path.storefrontId
      - text: Add credentials {auth} for account {account_identifier} on source {source_id} of storefront {storefront_id}.
        slots:
          auth: requestBody.auth
          account_identifier: requestBody.accountIdentifier
          source_id: path.sourceId
          storefront_id: path.storefrontId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefronts/{storefrontId}/sources/{sourceId}/adcp-connection'].post
  update:
    x-apievangelist-phrasing:
      intent: Connect a registered AdCP source account
      effect: write
      questions:
      - Once an AdCP source account is registered and mapped, how do I connect it for campaigns?
      - Do I need to supply endpoint URLs or secrets to connect an AdCP source?
      instructions:
      - text: Connect AdCP source {source_id} in storefront {storefront_id} for advertiser {advertiser_id} and account {account_id}.
        slots:
          source_id: path.sourceId
          storefront_id: path.storefrontId
          advertiser_id: requestBody.advertiserId
          account_id: requestBody.accountId
      - text: Project AdCP account {account_id} on source {source_id} (storefront {storefront_id}) for advertiser {advertiser_id} with credential {credential_id}.
        slots:
          account_id: requestBody.accountId
          source_id: path.sourceId
          storefront_id: path.storefrontId
          advertiser_id: requestBody.advertiserId
          credential_id: requestBody.credentialId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefronts/{storefrontId}/publishers'].get
  update:
    x-apievangelist-phrasing:
      intent: List publisher domains a storefront covers
      effect: read
      questions:
      - Which publisher domains can I reach through a storefront?
      - Can I see only the domains verified by adagents.json?
      instructions:
      - text: List publisher domains for storefront {storefront_id}.
        slots:
          storefront_id: path.storefrontId
      - text: Show only verified publisher domains in storefront {storefront_id}.
        slots:
          storefront_id: path.storefrontId
      method: generated
      generated: '2026-10-01'