# 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 Catalog API
  version: 1.0.0
extends: openapi/scope3-storefront-ad-server-catalog-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: 18
- target: $.paths['/esa/{esaId}/products'].get
  update:
    x-apievangelist-phrasing:
      intent: List wholesale products on an ad server source
      effect: read
      questions:
      - Which wholesale products are defined on my ad server source?
      - Can I see the product catalog of one connected ad server?
      instructions:
      - text: List wholesale products on ad server source {esa_id}.
        slots:
          esa_id: path.esaId
      - text: Show every product defined on ad server {esa_id}.
        slots:
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/products'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a wholesale product on an ad server source
      effect: write
      questions:
      - How do I add a new wholesale product to my ad server?
      - Can I create a product as a draft before activating it?
      instructions:
      - text: Create product {name} on ad server source {esa_id} with delivery type {delivery_type}.
        slots:
          name: requestBody.name
          esa_id: path.esaId
          delivery_type: requestBody.delivery_type
      - text: Add a {status} product {name} to ad server {esa_id} using inventory {inventory}.
        slots:
          status: requestBody.status
          name: requestBody.name
          esa_id: path.esaId
          inventory: requestBody.inventory
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/products:validate'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate a product draft without saving it
      effect: read
      questions:
      - Can I check a product definition for errors before creating it on the ad server?
      - What blocking errors and warnings would a product draft trigger?
      instructions:
      - text: Validate product draft {name} against ad server source {esa_id} without saving.
        slots:
          name: requestBody.name
          esa_id: path.esaId
      - text: 'Dry-check this product request for ad server {esa_id}: inventory {inventory}, formats {format_options}.'
        slots:
          esa_id: path.esaId
          inventory: requestBody.inventory
          format_options: requestBody.format_options
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/products/{productId}'].get
  update:
    x-apievangelist-phrasing:
      intent: View one wholesale product on an ad server source
      effect: read
      questions:
      - What's configured on a specific wholesale product in my ad server?
      - Can I fetch one product by id from an ad server source?
      instructions:
      - text: Show product {product_id} on ad server source {esa_id}.
        slots:
          product_id: path.productId
          esa_id: path.esaId
      - text: Get the configuration of wholesale product {product_id} from {esa_id}.
        slots:
          product_id: path.productId
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/products/{productId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a wholesale product's full definition
      effect: write
      questions:
      - Does editing a product on the ad server require sending the complete definition?
      - How do I fully replace a wholesale product's settings?
      instructions:
      - text: Replace product {product_id} on {esa_id} with name {name}, delivery {delivery_type} and inventory {inventory}.
        slots:
          product_id: path.productId
          esa_id: path.esaId
          name: requestBody.name
          delivery_type: requestBody.delivery_type
          inventory: requestBody.inventory
      - text: Overwrite the whole definition of product {product_id} on ad server {esa_id}.
        slots:
          product_id: path.productId
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/products/{productId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a wholesale product from an ad server source
      effect: destructive
      questions:
      - How do I remove a wholesale product from my ad server?
      - Can I delete a product I no longer sell?
      instructions:
      - text: Delete product {product_id} from ad server source {esa_id}.
        slots:
          product_id: path.productId
          esa_id: path.esaId
      - text: Remove wholesale product {product_id} on {esa_id}.
        slots:
          product_id: path.productId
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/products/{productId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Change only some fields of a wholesale product
      effect: write
      questions:
      - Can I change just a product's name or status without resending everything?
      - What happens to fields I leave out of a partial product update?
      instructions:
      - text: Set the status of product {product_id} on {esa_id} to {status}.
        slots:
          product_id: path.productId
          esa_id: path.esaId
          status: requestBody.status
      - text: Only rename product {product_id} on ad server {esa_id} to {name}, leaving other fields as they are.
        slots:
          product_id: path.productId
          esa_id: path.esaId
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/signals'].get
  update:
    x-apievangelist-phrasing:
      intent: List targeting signals on an ad server source
      effect: read
      questions:
      - Which named targeting definitions have I authored for an ad server source?
      - Can I see all signal mappings on one ad server?
      instructions:
      - text: List signals on ad server source {esa_id}.
        slots:
          esa_id: path.esaId
      - text: Show the targeting signal mappings for {esa_id}.
        slots:
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/signals'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a signal mapping on an ad server source
      effect: write
      questions:
      - How do I map ad-server targeting to a new named signal?
      - Can I preview a new signal mapping without saving it?
      instructions:
      - text: Create signal {signal_id} named {name} of value type {value_type} on {esa_id} with config {adapter_config}.
        slots:
          signal_id: requestBody.signalId
          name: requestBody.name
          value_type: requestBody.valueType
          esa_id: path.esaId
          adapter_config: requestBody.adapterConfig
      - text: Dry-run new signal {signal_id} ({name}, {value_type}) on {esa_id} with config {adapter_config}, dry_run {dry_run}.
        slots:
          signal_id: requestBody.signalId
          name: requestBody.name
          value_type: requestBody.valueType
          esa_id: path.esaId
          adapter_config: requestBody.adapterConfig
          dry_run: query.dry_run
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/signals/adapter-capabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: See what signal targeting an ad server supports
      effect: read
      questions:
      - What targeting types can my ad server adapter use for signals?
      - What adapter config shape does a signal need on this ad server?
      instructions:
      - text: Show signal capabilities for ad server source {esa_id}.
        slots:
          esa_id: path.esaId
      - text: Get the signal adapter config shape for {esa_id}.
        slots:
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/signals/candidates'].get
  update:
    x-apievangelist-phrasing:
      intent: Browse ad-server targeting that can back a signal
      effect: read
      questions:
      - Which audience segments and key-values on my ad server could back a signal?
      - Can I search ad-server targeting keys by name while authoring a signal?
      instructions:
      - text: Browse signal candidates on {esa_id} matching {q}.
        slots:
          esa_id: path.esaId
          q: query.q
      - text: List {candidate_type} targeting candidates under parent {parent_id} on ad server {esa_id}.
        slots:
          candidate_type: query.candidateType
          parent_id: query.parentId
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/signals/{signalId}'].get
  update:
    x-apievangelist-phrasing:
      intent: View one signal mapping on an ad server source
      effect: read
      questions:
      - How is a specific signal mapped to targeting on my ad server?
      - Can I fetch a single signal definition by id from an ad server?
      instructions:
      - text: Show signal {signal_id} on ad server source {esa_id}.
        slots:
          signal_id: path.signalId
          esa_id: path.esaId
      - text: Get the mapping for signal {signal_id} on {esa_id}.
        slots:
          signal_id: path.signalId
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/signals/{signalId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a signal mapping on an ad server source
      effect: write
      questions:
      - Can I preview changes to an existing ad-server signal before saving them?
      - Does replacing a signal mapping need the full definition again?
      instructions:
      - text: Replace signal {signal_id} on {esa_id} with name {name}, value type {value_type} and config {adapter_config}.
        slots:
          signal_id: path.signalId
          esa_id: path.esaId
          name: requestBody.name
          value_type: requestBody.valueType
          adapter_config: requestBody.adapterConfig
      - text: 'Dry-run replacing signal {body_signal_id} on {esa_id} path {signal_id}: {name}, {value_type}, {adapter_config}, dry_run {dry_run}.'
        slots:
          body_signal_id: requestBody.signalId
          esa_id: path.esaId
          signal_id: path.signalId
          name: requestBody.name
          value_type: requestBody.valueType
          adapter_config: requestBody.adapterConfig
          dry_run: query.dry_run
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/signals/{signalId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a signal mapping from an ad server source
      effect: destructive
      questions:
      - How do I remove a signal mapping from my ad server?
      - Can I delete a targeting signal I authored on an ad server source?
      instructions:
      - text: Delete signal {signal_id} from ad server source {esa_id}.
        slots:
          signal_id: path.signalId
          esa_id: path.esaId
      - text: Remove the {signal_id} mapping on {esa_id}.
        slots:
          signal_id: path.signalId
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/inventory/capabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: See what inventory selection an ad server supports
      effect: read
      questions:
      - Which inventory selector dimensions does my ad server adapter support?
      - Can my ad server discover publisher properties?
      instructions:
      - text: Show inventory capabilities for ad server source {esa_id}.
        slots:
          esa_id: path.esaId
      - text: List the selector dimensions ad server {esa_id} supports.
        slots:
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/inventory/publisher-properties'].get
  update:
    x-apievangelist-phrasing:
      intent: List publisher sites and apps on an ad server
      effect: read
      questions:
      - Which sites and apps does my ad server connection expose?
      - Can I filter publisher properties by domain?
      instructions:
      - text: List publisher properties on ad server source {esa_id}.
        slots:
          esa_id: path.esaId
      - text: Show all sites and apps exposed by {esa_id}.
        slots:
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/inventory/selectors'].get
  update:
    x-apievangelist-phrasing:
      intent: Search ad units and placements on an ad server
      effect: read
      questions:
      - How do I find the ad units that could back a new product?
      - Can I limit an inventory selector search to video or a certain environment?
      instructions:
      - text: Search {selector_type} on ad server {esa_id} for {q}.
        slots:
          selector_type: query.selectorType
          esa_id: path.esaId
          q: query.q
      - text: Find {media_type} {selector_type} inventory on {esa_id}.
        slots:
          media_type: query.mediaType
          selector_type: query.selectorType
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/creative-formats'].get
  update:
    x-apievangelist-phrasing:
      intent: List creative formats on an ad server source
      effect: read
      questions:
      - Which creative formats does my ad server support?
      - Can I filter ad server creative formats by asset type?
      instructions:
      - text: List creative formats on ad server source {esa_id}.
        slots:
          esa_id: path.esaId
      - text: Show {asset_type} creative formats on {esa_id}.
        slots:
          asset_type: query.assetType
          esa_id: path.esaId
      method: generated
      generated: '2026-10-01'