# 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 API
  version: 1.0.0
extends: openapi/scope3-storefront-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: 159
- target: $.paths['/account-mappings/summary'].get
  update:
    x-apievangelist-phrasing:
      intent: Summarize seller account mapping coverage
      effect: read
      questions:
      - How many buyer relationships do I have mapped across my active inventory sources?
      - What does the summary on the Buyer Account Mapping page count?
      instructions:
      - text: Show me the coverage counts for my seller account mappings.
      - text: Give me a quick summary of how many operator and brand relationships are mapped to active sources.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/account-mappings'].get
  update:
    x-apievangelist-phrasing:
      intent: List seller account relationships
      effect: read
      questions:
      - Which operator and brand relationships does my storefront own?
      - Can I search my seller account relationships by name and page through them?
      instructions:
      - text: List my seller account relationships matching {search}.
        slots:
          search: query.search
      - text: Show {limit} seller account relationships starting at offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/account-mappings/export'].get
  update:
    x-apievangelist-phrasing:
      intent: Export seller account mappings as CSV
      effect: read
      questions:
      - Can I download my current account mappings and the mapping template as CSV?
      - Where do I get the source-mapping template to fill in offline?
      instructions:
      - text: Export my seller account mappings and the blank mapping template as CSV files.
      - text: Download the healthy source-account mappings I currently have.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/account-mappings/reviews'].get
  update:
    x-apievangelist-phrasing:
      intent: List pending buyer account requests
      effect: read
      questions:
      - Which buyer account requests are waiting for me to approve or reject?
      - Do pending buyer account requests include the version I need to make a decision?
      instructions:
      - text: Show the buyer account requests awaiting my decision.
      - text: List {limit} pending buyer account requests from offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/account-mappings/reviews/{grantId}/decision'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve or reject a buyer account request
      effect: write
      questions:
      - Can I reject a buyer's account request, and do I have to give a reason?
      - What happens if I approve a buyer account request for Interchange-cleared billing?
      instructions:
      - text: Approve buyer account request {grantId}.
        slots:
          grantId: path.grantId
      - text: Reject buyer account request {grantId} with a reason.
        slots:
          grantId: path.grantId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/account-mappings/sources/{inventorySourceId}/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Refresh advertiser choices for an ad-server source
      effect: write
      questions:
      - Can I reload the advertiser list from my Google Ad Manager or FreeWheel source for account mapping?
      - Which ad servers support refreshing the source-account roster?
      instructions:
      - text: Refresh the advertiser account choices for inventory source {inventorySourceId}.
        slots:
          inventorySourceId: path.inventorySourceId
      - text: Pull the latest ad-server advertiser roster into account mapping for source {inventorySourceId}.
        slots:
          inventorySourceId: path.inventorySourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/account-mappings/imports/prepare'].post
  update:
    x-apievangelist-phrasing:
      intent: Prepare an account mapping feed upload
      effect: write
      questions:
      - How do I get a signed upload URL for my source_account_bindings.csv file?
      - Can I upload account mappings as a snapshot that covers specific inventory sources?
      instructions:
      - text: Prepare an account mapping feed upload in {mode} mode for revision {sourceRevision}.
        slots:
          mode: requestBody.mode
          sourceRevision: requestBody.sourceRevision
      - text: Reserve a mapping feed revision for {file} covering sources {coveredInventorySourceKeys}.
        slots:
          file: requestBody.file
          coveredInventorySourceKeys: requestBody.coveredInventorySourceKeys
      method: generated
      generated: '2026-10-01'
- target: $.paths['/account-mappings/imports/{revisionId}/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Validate and preview an account mapping feed
      effect: read
      questions:
      - Can I see which rows of my uploaded account mapping file are invalid before applying it?
      - What impact will my mapping feed revision have before I commit it?
      instructions:
      - text: Validate and preview uploaded account mapping revision {revisionId}.
        slots:
          revisionId: path.revisionId
      - text: Check mapping feed revision {revisionId} for bad rows and get a preview token.
        slots:
          revisionId: path.revisionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/account-mappings/imports/{revisionId}/commit'].post
  update:
    x-apievangelist-phrasing:
      intent: Commit a previewed account mapping feed
      effect: write
      questions:
      - Will committing a mapping feed overwrite the manual mappings I made?
      - Can I apply only part of a reviewed account mapping feed?
      instructions:
      - text: Commit account mapping revision {revisionId} using preview token {previewToken}.
        slots:
          revisionId: path.revisionId
          previewToken: requestBody.previewToken
      - text: Apply mapping feed {revisionId} with idempotency key {idempotencyKey} and preview token {previewToken}.
        slots:
          revisionId: path.revisionId
          idempotencyKey: requestBody.idempotencyKey
          previewToken: requestBody.previewToken
      method: generated
      generated: '2026-10-01'
- target: $.paths['/account-mappings/imports/{revisionId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Check an account mapping feed revision
      effect: read
      questions:
      - What state is my account mapping feed upload in right now?
      - Where can I see diagnostics for a mapping feed revision I uploaded?
      instructions:
      - text: Show the status and diagnostics of mapping feed revision {revisionId}.
        slots:
          revisionId: path.revisionId
      - text: Get the lifecycle and impact of account mapping revision {revisionId}.
        slots:
          revisionId: path.revisionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my storefront
      effect: read
      questions:
      - What is my storefront currently configured as?
      - Can I see my storefront's name, publisher domain and plan?
      instructions:
      - text: Show me my storefront.
      - text: Fetch my current storefront configuration.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront'].put
  update:
    x-apievangelist-phrasing:
      intent: Update storefront settings
      effect: write
      questions:
      - Can I pause my storefront so it stops transacting?
      - How do I change which countries and currencies my storefront accepts?
      - Can I update the demand contact email and logo buyers see?
      instructions:
      - text: Pause my storefront by setting paused to {isPaused}.
        slots:
          isPaused: requestBody.isPaused
      - text: Change my storefront's default currency to {defaultCurrency}.
        slots:
          defaultCurrency: requestBody.defaultCurrency
      - text: Set the storefront demand contact to {demandContactName} at {demandContactEmail}.
        slots:
          demandContactName: requestBody.demandContactName
          demandContactEmail: requestBody.demandContactEmail
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a storefront
      effect: write
      questions:
      - What do I need to set up a new storefront?
      - Is creating a storefront safe to repeat if I already have one?
      instructions:
      - text: Create a storefront named {name} for publisher domain {publisherDomain}.
        slots:
          name: requestBody.name
          publisherDomain: requestBody.publisherDomain
      - text: Set up my storefront {name} with default currency {defaultCurrency}.
        slots:
          name: requestBody.name
          defaultCurrency: requestBody.defaultCurrency
      method: generated
      generated: '2026-10-01'
- target: $.paths['/storefront'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch legacy storefront capabilities
      effect: write
      questions:
      - Can I change just the storefront capabilities without resending the whole configuration?
      - Where do I update my storefront's setup intent on its own?
      instructions:
      - text: Patch only my storefront capabilities to {capabilities}.
        slots:
          capabilities: requestBody.capabilities
      - text: Update just the storefront setup intent to {setupIntent}.
        slots:
          setupIntent: requestBody.setupIntent
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demo'].get
  update:
    x-apievangelist-phrasing:
      intent: Get my Demo Storefront
      effect: read
      questions:
      - Do I have a Demo Storefront, and when does its lease expire?
      - What synthetic profile is my demo storefront running on?
      instructions:
      - text: Show my Demo Storefront and its lease status.
      - text: Check whether a demo storefront exists for my account.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demo'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a seven-day Demo Storefront
      effect: write
      questions:
      - Can I spin up a demo storefront to try things without real side effects?
      - How long does a new Demo Storefront last?
      instructions:
      - text: Create a Demo Storefront from profile {profileId}.
        slots:
          profileId: requestBody.profileId
      - text: Start a demo storefront using profile {profileId} version {profileVersion}.
        slots:
          profileId: requestBody.profileId
          profileVersion: requestBody.profileVersion
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demo'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete my Demo Storefront
      effect: destructive
      questions:
      - Does deleting my demo storefront remove my customer account too?
      - Can I throw away the demo storefront and its synthetic data?
      instructions:
      - text: Delete my Demo Storefront.
      - text: Tear down the demo storefront and all its synthetic resources.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demo/reset'].post
  update:
    x-apievangelist-phrasing:
      intent: Reset the Demo Storefront
      effect: destructive
      questions:
      - Can I rebuild my demo storefront back to its starting state?
      - Does resetting the demo storefront extend its lease?
      instructions:
      - text: Reset my Demo Storefront to its pinned profile.
      - text: Rebuild the demo storefront from scratch without extending it.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demo/source-recipes'].get
  update:
    x-apievangelist-phrasing:
      intent: List demo source recipes
      effect: read
      questions:
      - Which synthetic inventory sources can I add to a demo storefront?
      - What composition presets are available for demo storefronts?
      instructions:
      - text: List the demo source recipes I can attach.
      - text: Show the synthetic modular-source recipes for demos.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demo/sources'].post
  update:
    x-apievangelist-phrasing:
      intent: Attach synthetic sources to the demo
      effect: write
      questions:
      - Can I add several synthetic inventory sources to my demo storefront at once?
      - How do I give my demo storefront some fake inventory to sell?
      instructions:
      - text: Attach demo source recipes {recipeIds} to my Demo Storefront.
        slots:
          recipeIds: requestBody.recipeIds
      - text: Add the synthetic sources {recipeIds} to the active demo.
        slots:
          recipeIds: requestBody.recipeIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demo/sources/{sourceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a source from the demo
      effect: destructive
      questions:
      - Can I take one synthetic source back out of my demo storefront?
      - What happens to the generated inventory when I remove a demo source?
      instructions:
      - text: Remove demo source {sourceId} from my Demo Storefront.
        slots:
          sourceId: path.sourceId
      - text: Detach synthetic source {sourceId} and its inventory from the demo.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demo/extend'].post
  update:
    x-apievangelist-phrasing:
      intent: Extend the Demo Storefront lease
      effect: write
      questions:
      - Can I keep my demo storefront longer than seven days?
      - How many days can I extend a demo storefront by?
      instructions:
      - text: Extend my Demo Storefront by {days} days.
        slots:
          days: requestBody.days
      - text: Push back the demo storefront expiry.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/readiness'].get
  update:
    x-apievangelist-phrasing:
      intent: Check if the storefront can go live
      effect: read
      questions:
      - Is my storefront ready to go live?
      - What is blocking my storefront from launching?
      instructions:
      - text: Check my storefront's go-live readiness.
      - text: List the blocking checks for inventory sources and agent auth before launch.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/readiness/compliance'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the latest compliance check
      effect: read
      questions:
      - Did my storefront pass its last compliance check?
      - Has a compliance readiness check ever run on my storefront?
      instructions:
      - text: Show my storefront's most recent compliance result.
      - text: Get the last compliance readiness check.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/readiness/compliance/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-run the storefront compliance check
      effect: write
      questions:
      - Can I re-run compliance against just one agent?
      - How do I recheck compliance after fixing a source health issue?
      instructions:
      - text: Re-run the compliance check for agent {agentId}.
        slots:
          agentId: requestBody.agentId
      - text: Recheck compliance across all my storefront's agents now.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/resolve-brand'].post
  update:
    x-apievangelist-phrasing:
      intent: Look up a brand profile by domain
      effect: read
      questions:
      - Is there a brand profile on agenticadvertising.org for this domain?
      - Can I get a brand's name and logo just from its website domain?
      instructions:
      - text: Resolve the brand profile for {domain}.
        slots:
          domain: requestBody.domain
      - text: Look up the brand name and logo for domain {domain}.
        slots:
          domain: requestBody.domain
      method: generated
      generated: '2026-10-01'
- target: $.paths['/discover-agents'].get
  update:
    x-apievangelist-phrasing:
      intent: Find agents authorized for a domain
      effect: read
      questions:
      - Which operator and publisher agents are authorized to sell a given domain?
      - Can I bypass the cached agent discovery result for a domain?
      instructions:
      - text: Discover the authorized agents for {domain}.
        slots:
          domain: query.domain
      - text: Find agents for {domain} and bypass the cache with refresh {refresh}.
        slots:
          domain: query.domain
          refresh: query.refresh
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources'].get
  update:
    x-apievangelist-phrasing:
      intent: List inventory sources
      effect: read
      questions:
      - Which inventory sources are connected to my storefront?
      - What sources of inventory am I selling from today?
      instructions:
      - text: List all my storefront's inventory sources.
      - text: Show every inventory source on the storefront.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources'].post
  update:
    x-apievangelist-phrasing:
      intent: Create an inventory source
      effect: write
      questions:
      - Can I add a new inventory source and register its sales agent at the same time?
      - What authentication types can a new inventory source use?
      instructions:
      - text: Create an inventory source named {name} pointing at {endpointUrl}.
        slots:
          name: requestBody.name
          endpointUrl: requestBody.endpointUrl
      - text: Add inventory source {name} using protocol {protocol} and {authenticationType} auth.
        slots:
          name: requestBody.name
          protocol: requestBody.protocol
          authenticationType: requestBody.authenticationType
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an inventory source
      effect: read
      questions:
      - What are the settings of one specific inventory source?
      - Can I look up an inventory source by its source ID?
      instructions:
      - text: Show inventory source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Get the details of source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an inventory source
      effect: write
      questions:
      - Does changing an inventory source's status affect its linked agent?
      - Can I point an existing inventory source at a new endpoint URL?
      instructions:
      - text: Set the status of inventory source {sourceId} to {status}.
        slots:
          sourceId: path.sourceId
          status: requestBody.status
      - text: Rename inventory source {sourceId} to {name}.
        slots:
          sourceId: path.sourceId
          name: requestBody.name
      - text: Change the endpoint of source {sourceId} to {endpointUrl}.
        slots:
          sourceId: path.sourceId
          endpointUrl: requestBody.endpointUrl
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete an inventory source
      effect: destructive
      questions:
      - What happens to the linked agent when I delete an inventory source?
      - Can I permanently remove an inventory source from my storefront?
      instructions:
      - text: Delete inventory source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Remove source {sourceId} and disable its agent.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/diagnostics'].get
  update:
    x-apievangelist-phrasing:
      intent: Get call health diagnostics for a source
      effect: read
      questions:
      - Is my inventory source timing out or failing calls lately?
      - How has a source's latency moved compared with the prior window?
      instructions:
      - text: Show call health diagnostics for source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Get latency and failure stats for source {sourceId} over the last {windowHours} hours.
        slots:
          sourceId: path.sourceId
          windowHours: query.windowHours
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/mapping-workspace'].get
  update:
    x-apievangelist-phrasing:
      intent: View a source's mapping workspace
      effect: read
      questions:
      - Can I see how my storefront identities map through one inventory source?
      - Which product paths on a source are ready versus inactive?
      instructions:
      - text: Open the mapping workspace for source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Show storefront-built and agent-supplied mapping readiness for source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/tests/discovery'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a product discovery test on a source
      effect: read
      questions:
      - Can I test whether a sales agent returns products without creating a media buy?
      - Does a discovery test on a source spend any money?
      instructions:
      - text: Run a discovery test against source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Test get_products on source {sourceId} with the brief {brief}.
        slots:
          sourceId: path.sourceId
          brief: requestBody.brief
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/wholesale-pricing/template'].get
  update:
    x-apievangelist-phrasing:
      intent: Download the wholesale pricing CSV template
      effect: read
      questions:
      - Where do I get a pre-filled wholesale avails and pricing template for a source?
      - Does the wholesale pricing template list each ad-server selector my products use?
      instructions:
      - text: Download the wholesale pricing template for source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Get the pre-filled avails and pricing CSV for source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/property-mappings'].get
  update:
    x-apievangelist-phrasing:
      intent: List property and tag mappings for a source
      effect: read
      questions:
      - Which properties and tags have I mapped on a managed sales-agent source?
      - Can I review my seller-authored property mappings?
      instructions:
      - text: List the property mappings on source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Show the tag and property mappings I authored for source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/property-mappings'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace all property mappings for a source
      effect: write
      questions:
      - Can I dry-run a replacement of my property mappings before applying it?
      - Does replacing property mappings overwrite all of them at once?
      instructions:
      - text: Dry-run replacing the property mappings on source {sourceId} with dry run {dry_run}.
        slots:
          sourceId: path.sourceId
          dry_run: query.dry_run
      - text: Replace every property and tag mapping on source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/ad-servers/citrusad'].post
  update:
    x-apievangelist-phrasing:
      intent: Connect CitrusAd as an ad server
      effect: write
      questions:
      - Can I connect CitrusAd for sponsored products to my storefront?
      - What CitrusAd details do I need to connect it, like team ID and namespaces?
      instructions:
      - text: Connect CitrusAd team {teamId} in the {environment} environment with namespaces {namespaces}.
        slots:
          teamId: requestBody.teamId
          environment: requestBody.environment
          namespaces: requestBody.namespaces
      - text: Hook up CitrusAd in {environment} for team {teamId}, namespaces {namespaces}, priced in {defaultCurrency}.
        slots:
          environment: requestBody.environment
          teamId: requestBody.teamId
          namespaces: requestBody.namespaces
          defaultCurrency: requestBody.defaultCurrency
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/ad-servers/citrusad/credentials/{credentialKind}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rotate a CitrusAd credential
      effect: write
      questions:
      - Can I swap in a new CitrusAd credential on an existing source?
      - Is the rotated CitrusAd secret ever stored in the source config?
      instructions:
      - text: Rotate the CitrusAd {credentialKind} credential on source {sourceId}.
        slots:
          credentialKind: path.credentialKind
          sourceId: path.sourceId
      - text: Replace the CitrusAd {credentialKind} credential for source {sourceId} with {auth}.
        slots:
          credentialKind: path.credentialKind
          sourceId: path.sourceId
          auth: requestBody.auth
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/ad-servers/citrusad/credentials/{credentialKind}'].post
  update:
    x-apievangelist-phrasing:
      intent: Save a first CitrusAd credential
      effect: write
      questions:
      - Where do I store my CitrusAd credentials after connecting it?
      - Will the CitrusAd credential I save ever be returned by the API?
      instructions:
      - text: Save a new CitrusAd {credentialKind} credential for source {sourceId}.
        slots:
          credentialKind: path.credentialKind
          sourceId: path.sourceId
      - text: Store CitrusAd {credentialKind} auth {auth} on source {sourceId}.
        slots:
          credentialKind: path.credentialKind
          auth: requestBody.auth
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/ad-servers/citrusad/credentials/{credentialKind}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a CitrusAd credential
      effect: destructive
      questions:
      - Can I revoke a CitrusAd credential and delete its stored secret?
      - What happens when I revoke CitrusAd access on a source?
      instructions:
      - text: Revoke the CitrusAd {credentialKind} credential on source {sourceId}.
        slots:
          credentialKind: path.credentialKind
          sourceId: path.sourceId
      - text: Delete the stored CitrusAd {credentialKind} secret for source {sourceId}.
        slots:
          credentialKind: path.credentialKind
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/modular/feed'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a feed-backed modular source
      effect: write
      questions:
      - Can I create an inventory source from an uploaded avails feed?
      - Does a feed-backed modular source include a booking ledger by default?
      instructions:
      - text: Create a modular avails-feed source named {name}.
        slots:
          name: requestBody.name
      - text: Set up feed source {name} with the booking ledger set to {includeBookingLedger}.
        slots:
          name: requestBody.name
          includeBookingLedger: requestBody.includeBookingLedger
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/modular/cadent-demo'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or reset a Cadent demo source
      effect: write
      questions:
      - Can I set up a Cadent-backed demo source for a live demo?
      - How do I reset the Cadent demo source with fresh avails?
      instructions:
      - text: Create a Cadent demo modular source named {name}.
        slots:
          name: requestBody.name
      - text: Reset the Cadent demo source with reset {reset} and seed avails {seedAvails}.
        slots:
          reset: requestBody.reset
          seedAvails: requestBody.seedAvails
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/modular/freewheel-sandbox'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a FreeWheel sandbox source
      effect: write
      questions:
      - Can I create a FreeWheel sandbox source with live taxonomy selectors?
      - Do I need to provide FreeWheel credentials for the sandbox source?
      instructions:
      - text: Create a FreeWheel sandbox modular source named {name}.
        slots:
          name: requestBody.name
      - text: Set up the FreeWheel sandbox source for advertiser {advertiserId}.
        slots:
          advertiserId: requestBody.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular'].get
  update:
    x-apievangelist-phrasing:
      intent: Check a modular source's setup readiness
      effect: read
      questions:
      - What setup fields are still missing on my modular inventory source?
      - Which lifecycle stage is a modular source in, and how much open work does it have?
      instructions:
      - text: Show the readiness of modular source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: List missing setup fields and issues for modular source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/avails-feed'].post
  update:
    x-apievangelist-phrasing:
      intent: Load confirmed avails into a modular source
      effect: write
      questions:
      - How do I load avails into a modular source's static feed after reviewing them?
      - Can I send avails as CSV text instead of structured rows?
      instructions:
      - text: Ingest the reviewed avails into modular source {sourceId} with confirmed {confirmed}.
        slots:
          sourceId: path.sourceId
          confirmed: requestBody.confirmed
      - text: Upsert avails from this CSV {csvText} into modular source {sourceId}.
        slots:
          csvText: requestBody.csvText
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/avails-feed/upload'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview a modular avails file
      effect: read
      questions:
      - Can I check an XLSX avails file for errors before loading it into a modular source?
      - Which file formats can I preview for modular avails?
      instructions:
      - text: Parse avails file {file} for modular source {sourceId} without committing.
        slots:
          file: requestBody.file
          sourceId: path.sourceId
      - text: Preview row diagnostics for the avails spreadsheet {file} on source {sourceId}.
        slots:
          file: requestBody.file
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/products'].get
  update:
    x-apievangelist-phrasing:
      intent: List products on a modular source
      effect: read
      questions:
      - What products does my modular source expose from its avails?
      - Can I see the product projections built from normalized avails?
      instructions:
      - text: List the products on modular source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Show product projections from avails on source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/work-items'].get
  update:
    x-apievangelist-phrasing:
      intent: List work items on a modular source
      effect: read
      questions:
      - Which source-side work items are open or blocked on my modular source?
      - Can I filter modular work items by media buy or buyer?
      instructions:
      - text: List open work items for modular source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Show work items on source {sourceId} with status {status}.
        slots:
          sourceId: path.sourceId
          status: query.status
      - text: Find work items on source {sourceId} for media buy {mediaBuyId}.
        slots:
          sourceId: path.sourceId
          mediaBuyId: query.mediaBuyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/work-items/{workItemId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a modular source work item
      effect: read
      questions:
      - What is the event history of one modular work item?
      - Can I open a single source-side work item to see its details?
      instructions:
      - text: Show work item {workItemId} on modular source {sourceId}.
        slots:
          workItemId: path.workItemId
          sourceId: path.sourceId
      - text: Get the history of work item {workItemId} for source {sourceId}.
        slots:
          workItemId: path.workItemId
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/work-items/{workItemId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a modular source work item
      effect: write
      questions:
      - Can I assign a modular work item to someone or mark it blocked?
      - Is it possible to add notes to a source-side work item without finishing it?
      instructions:
      - text: Assign work item {workItemId} on source {sourceId} to {assignedTo}.
        slots:
          workItemId: path.workItemId
          sourceId: path.sourceId
          assignedTo: requestBody.assignedTo
      - text: Mark work item {workItemId} on source {sourceId} blocked because {blockedReason}.
        slots:
          workItemId: path.workItemId
          sourceId: path.sourceId
          blockedReason: requestBody.blockedReason
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/work-items/{workItemId}/complete'].post
  update:
    x-apievangelist-phrasing:
      intent: Complete a modular source work item
      effect: write
      questions:
      - How do I close out a modular work item once the task is done?
      - Does completing a work item trigger anything else on the source?
      instructions:
      - text: Complete work item {workItemId} on modular source {sourceId}.
        slots:
          workItemId: path.workItemId
          sourceId: path.sourceId
      - text: Finish work item {workItemId} on source {sourceId} with notes {notes}.
        slots:
          workItemId: path.workItemId
          sourceId: path.sourceId
          notes: requestBody.notes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/inventory/capabilities'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a modular source's targeting capabilities
      effect: read
      questions:
      - Which selector and targeting capabilities does my modular source support?
      - What taxonomy selectors does the FreeWheel sandbox source expose?
      instructions:
      - text: Show the targeting capabilities of modular source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: List selector types available on source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/inventory/selectors'].get
  update:
    x-apievangelist-phrasing:
      intent: Search taxonomy selectors on a modular source
      effect: read
      questions:
      - Can I search the FreeWheel taxonomy for a selector by name?
      - Does selector search return avails or forecasted capacity?
      instructions:
      - text: Search {selectorType} selectors on source {sourceId} for {q}.
        slots:
          selectorType: query.selectorType
          sourceId: path.sourceId
          q: query.q
      - text: List child {selectorType} selectors under {parentId} on source {sourceId}.
        slots:
          selectorType: query.selectorType
          parentId: query.parentId
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/reservations'].post
  update:
    x-apievangelist-phrasing:
      intent: Hold capacity on a modular product
      effect: write
      questions:
      - Can I hold impressions on a modular product for a media buy without overbooking?
      - How long can a modular inventory hold last?
      instructions:
      - text: Reserve {requestedImpressions} impressions of product {productId} on source {sourceId} for media buy {mediaBuyId} and buyer {buyerCustomerId}.
        slots:
          requestedImpressions: requestBody.requestedImpressions
          productId: requestBody.productId
          sourceId: path.sourceId
          mediaBuyId: requestBody.mediaBuyId
          buyerCustomerId: requestBody.buyerCustomerId
      - text: Hold avail {availId} on source {sourceId} for {holdMinutes} minutes for buy {mediaBuyId}, buyer {buyerCustomerId}, {requestedImpressions} impressions.
        slots:
          availId: requestBody.availId
          sourceId: path.sourceId
          holdMinutes: requestBody.holdMinutes
          mediaBuyId: requestBody.mediaBuyId
          buyerCustomerId: requestBody.buyerCustomerId
          requestedImpressions: requestBody.requestedImpressions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/bookings/finalize'].post
  update:
    x-apievangelist-phrasing:
      intent: Hand off a held reservation for booking
      effect: write
      questions:
      - How do I turn a held modular reservation into Cadent XML or FreeWheel work items?
      - Does preparing the booking handoff mark the reservation as booked?
      instructions:
      - text: Prepare the booking handoff on source {sourceId} for media buy {mediaBuyId}, buyer {buyerCustomerId}, avail {availId}.
        slots:
          sourceId: path.sourceId
          mediaBuyId: requestBody.mediaBuyId
          buyerCustomerId: requestBody.buyerCustomerId
          availId: requestBody.availId
      - text: Finalize the held booking for campaign {campaignName} on source {sourceId}, buy {mediaBuyId}, buyer {buyerCustomerId}, avail {availId}.
        slots:
          campaignName: requestBody.campaignName
          sourceId: path.sourceId
          mediaBuyId: requestBody.mediaBuyId
          buyerCustomerId: requestBody.buyerCustomerId
          availId: requestBody.availId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/bookings/release'].post
  update:
    x-apievangelist-phrasing:
      intent: Release a modular inventory hold or booking
      effect: destructive
      questions:
      - Can I give back capacity from a held modular reservation?
      - What happens to the avail when I cancel a locally booked reservation?
      instructions:
      - text: Release the hold on avail {availId} at source {sourceId} for media buy {mediaBuyId}, buyer {buyerCustomerId}.
        slots:
          availId: requestBody.availId
          sourceId: path.sourceId
          mediaBuyId: requestBody.mediaBuyId
          buyerCustomerId: requestBody.buyerCustomerId
      - text: Cancel the modular booking for buy {mediaBuyId} by buyer {buyerCustomerId} on avail {availId}, source {sourceId}.
        slots:
          mediaBuyId: requestBody.mediaBuyId
          buyerCustomerId: requestBody.buyerCustomerId
          availId: requestBody.availId
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/modules/{moduleInstanceId}/config'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a module's config on a modular source
      effect: write
      questions:
      - Can I change one module's non-secret config on a modular source?
      - Is module config merged or replaced when I update it?
      instructions:
      - text: Update module {moduleInstanceId} on source {sourceId} with config {config}.
        slots:
          moduleInstanceId: path.moduleInstanceId
          sourceId: path.sourceId
          config: requestBody.config
      - text: Replace module {moduleInstanceId} config on source {sourceId} with {config} and merge {merge}.
        slots:
          moduleInstanceId: path.moduleInstanceId
          sourceId: path.sourceId
          config: requestBody.config
          merge: requestBody.merge
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/modules/{moduleInstanceId}/credentials/{credentialKind}'].put
  update:
    x-apievangelist-phrasing:
      intent: Rotate a modular module credential
      effect: write
      questions:
      - Can I replace a module's credential and revoke the old secret in one step?
      - How do I rotate the provider credential on a private modular module?
      instructions:
      - text: Rotate the {credentialKind} credential on module {moduleInstanceId} of source {sourceId}.
        slots:
          credentialKind: path.credentialKind
          moduleInstanceId: path.moduleInstanceId
          sourceId: path.sourceId
      - text: Swap module {moduleInstanceId} on source {sourceId} to new {credentialKind} auth {auth}.
        slots:
          moduleInstanceId: path.moduleInstanceId
          sourceId: path.sourceId
          credentialKind: path.credentialKind
          auth: requestBody.auth
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/modules/{moduleInstanceId}/credentials/{credentialKind}'].post
  update:
    x-apievangelist-phrasing:
      intent: Store a credential for a modular module
      effect: write
      questions:
      - Where do I store a provider credential for a modular source module the first time?
      - Is a module credential returned after I save it?
      instructions:
      - text: Store a {credentialKind} credential for module {moduleInstanceId} on source {sourceId}.
        slots:
          credentialKind: path.credentialKind
          moduleInstanceId: path.moduleInstanceId
          sourceId: path.sourceId
      - text: Add new {credentialKind} auth {auth} to module {moduleInstanceId} of source {sourceId}.
        slots:
          credentialKind: path.credentialKind
          auth: requestBody.auth
          moduleInstanceId: path.moduleInstanceId
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/modular/modules/{moduleInstanceId}/credentials/{credentialKind}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Revoke a modular module credential
      effect: destructive
      questions:
      - Can I revoke a modular module's credential and delete its secret?
      - What does revoking a module credential do to the live connection?
      instructions:
      - text: Revoke the {credentialKind} credential on module {moduleInstanceId} of source {sourceId}.
        slots:
          credentialKind: path.credentialKind
          moduleInstanceId: path.moduleInstanceId
          sourceId: path.sourceId
      - text: Delete the stored {credentialKind} secret for module {moduleInstanceId} on source {sourceId}.
        slots:
          credentialKind: path.credentialKind
          moduleInstanceId: path.moduleInstanceId
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/feed/preview'].post
  update:
    x-apievangelist-phrasing:
      intent: Preview an inventory feed revision
      effect: read
      questions:
      - Can I preview a wholesale avails and pricing feed before committing it?
      - Which feed contracts can I preview with JSON rows?
      instructions:
      - text: Preview a {contractId} feed revision on source {sourceId}.
        slots:
          contractId: requestBody.contractId
          sourceId: path.sourceId
      - text: Build a preview revision on source {sourceId} from this JSON {jsonText} under contract {contractId}.
        slots:
          sourceId: path.sourceId
          jsonText: requestBody.jsonText
          contractId: requestBody.contractId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/feed/upload'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload a feed file for preview
      effect: read
      questions:
      - Can I upload an Excel or CSV file as an inventory feed instead of posting JSON?
      - Does a multipart feed upload commit right away?
      instructions:
      - text: Upload feed file {file} to source {sourceId} under contract {contractId}.
        slots:
          file: requestBody.file
          sourceId: path.sourceId
          contractId: requestBody.contractId
      - text: Send the spreadsheet {file} as a {contractId} feed preview for source {sourceId}.
        slots:
          file: requestBody.file
          contractId: requestBody.contractId
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/feed/commit'].post
  update:
    x-apievangelist-phrasing:
      intent: Commit a previewed feed revision
      effect: write
      questions:
      - What happens if someone else committed a feed after my preview?
      - How do I promote a previewed feed revision to live?
      instructions:
      - text: Commit revision {revision} of feed {feedId} on source {sourceId} with baseline {previewBaseline}.
        slots:
          revision: requestBody.revision
          feedId: requestBody.feedId
          sourceId: path.sourceId
          previewBaseline: requestBody.previewBaseline
      - text: Promote the previewed feed {feedId} revision {revision} to committed on source {sourceId} using {previewBaseline}.
        slots:
          feedId: requestBody.feedId
          revision: requestBody.revision
          sourceId: path.sourceId
          previewBaseline: requestBody.previewBaseline
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/feed/push'].post
  update:
    x-apievangelist-phrasing:
      intent: Push a feed revision without preview
      effect: write
      questions:
      - Can I ingest an inventory feed in one call without the preview step?
      - Is there a dry-run option when pushing a feed directly?
      instructions:
      - text: Push a {contractId} feed straight to source {sourceId}.
        slots:
          contractId: requestBody.contractId
          sourceId: path.sourceId
      - text: Dry-run pushing {contractId} feed CSV {csvText} to source {sourceId} with dry run {dryRun}.
        slots:
          contractId: requestBody.contractId
          csvText: requestBody.csvText
          sourceId: path.sourceId
          dryRun: requestBody.dryRun
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/esa'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the ad-server connection for a source
      effect: read
      questions:
      - What is the ad-server connection state behind one of my inventory sources?
      - Is the ad server linked to this inventory source connected?
      instructions:
      - text: Show the ad-server connection for inventory source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Read the ad-server connection state of source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get ad-server health by inventory source
      effect: read
      questions:
      - How healthy is the ad-server adapter behind an inventory source, looked up by source ID?
      - Can I include recent sync runs in an inventory source's operational status?
      instructions:
      - text: Get the operational status of inventory source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Show status for inventory source {sourceId} including the last {syncHistoryLimit} syncs.
        slots:
          sourceId: path.sourceId
          syncHistoryLimit: query.syncHistoryLimit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/sync-history'].get
  update:
    x-apievangelist-phrasing:
      intent: List sync runs by inventory source
      effect: read
      questions:
      - Can I drill into past sync runs for an inventory source by its source ID?
      - Which syncs failed on an inventory source recently?
      instructions:
      - text: List sync history for inventory source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Show {status} {syncType} sync runs for inventory source {sourceId}.
        slots:
          status: query.status
          syncType: query.syncType
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/launch'].post
  update:
    x-apievangelist-phrasing:
      intent: Open the ad-server admin UI from a source
      effect: write
      questions:
      - Can I get a one-time link into the managed admin UI for an inventory source?
      - Is it possible to deep-link to a specific admin page from an inventory source?
      instructions:
      - text: Mint an admin UI launch link for inventory source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Open the managed admin for inventory source {sourceId} at page {path}.
        slots:
          sourceId: path.sourceId
          path: requestBody.path
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/ad-server'].put
  update:
    x-apievangelist-phrasing:
      intent: Set ad-server config on a source
      effect: write
      questions:
      - How do I set the ad-server configuration on an inventory source with a full replace?
      - Is the ad-server config update a full replacement or a partial change?
      instructions:
      - text: Replace the ad-server config on inventory source {sourceId} with PUT.
        slots:
          sourceId: path.sourceId
      - text: Set new ad-server settings on source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/ad-server'].patch
  update:
    x-apievangelist-phrasing:
      intent: Replace ad-server config via legacy PATCH
      effect: write
      questions:
      - Can my old client keep using PATCH to replace an inventory source's ad-server config?
      - Is there a PATCH alias for migrating from the legacy esa ad-server route?
      instructions:
      - text: Use the legacy PATCH alias to replace ad-server config on source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Send the ad-server config for source {sourceId} via PATCH for backwards compatibility.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/adapter-config'].put
  update:
    x-apievangelist-phrasing:
      intent: Rotate ad-server adapter credentials
      effect: write
      questions:
      - Can I rotate FreeWheel or SpringServe credentials without losing products and sync history?
      - Where do I update adapter credentials on an already provisioned ad-server source?
      instructions:
      - text: Rotate the ad-server adapter credentials on source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Update the FreeWheel adapter credentials in place for source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/test-connection'].post
  update:
    x-apievangelist-phrasing:
      intent: Test ad-server reachability by inventory source
      effect: read
      questions:
      - Can the adapter reach my ad server with the credentials on this inventory source?
      - How can I probe an inventory source's ad-server connection by source ID?
      instructions:
      - text: Test the ad-server connection for inventory source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Probe ad-server reachability on source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Start ad-server syncs by inventory source
      effect: write
      questions:
      - Can I kick off a fresh ad-server sync for an inventory source by its source ID?
      - What does an inventory source refresh return if a sync is already running?
      instructions:
      - text: Refresh the ad-server snapshot for inventory source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Start sync runs for source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/deactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Deactivate an ad-server source by source ID
      effect: destructive
      questions:
      - Can I switch off an ad-server inventory source but keep it for later?
      - Does deactivating an inventory source's ad server delete the connection?
      instructions:
      - text: Deactivate the ad-server behind inventory source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Soft-delete ad-server source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/inventory-sources/{sourceId}/reactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Reactivate an ad-server source by source ID
      effect: write
      questions:
      - Can I turn a deactivated inventory source's ad server back on?
      - What if the upstream managed source no longer exists when I reactivate by source ID?
      instructions:
      - text: Reactivate the ad-server behind inventory source {sourceId}.
        slots:
          sourceId: path.sourceId
      - text: Re-enable deactivated source {sourceId}.
        slots:
          sourceId: path.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/service-account'].post
  update:
    x-apievangelist-phrasing:
      intent: Ensure the ad-server service account exists
      effect: write
      questions:
      - What service account email do I grant access to in my ad server?
      - Is a platform service account provisioned for managing my ad server sources?
      instructions:
      - text: Make sure my ad-server service account exists and give me its email.
      - text: Provision the platform service account for ad server sources.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa'].get
  update:
    x-apievangelist-phrasing:
      intent: List ad server connections
      effect: read
      questions:
      - Which ad server connections do I have, and what type is each?
      - Are any of my ad server source connections inactive?
      instructions:
      - text: List all my ad server connections.
      - text: Show my ad server sources with their type and status.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an ad server connection
      effect: read
      questions:
      - Can I look up one ad server source by its connection ID?
      - What are the details of a specific ad server connection?
      instructions:
      - text: Show ad server connection {esaId}.
        slots:
          esaId: path.esaId
      - text: Get the ad server source with connection ID {esaId}.
        slots:
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/test-connection'].post
  update:
    x-apievangelist-phrasing:
      intent: Test an ad server connection by connection ID
      effect: read
      questions:
      - Can the upstream agent reach my ad server using a given connection ID?
      - Are the credentials on an ad server connection working?
      instructions:
      - text: Test ad server connection {esaId}.
        slots:
          esaId: path.esaId
      - text: Check credentials for connection {esaId} against the ad server.
        slots:
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/refresh'].post
  update:
    x-apievangelist-phrasing:
      intent: Start ad server syncs by connection ID
      effect: write
      questions:
      - Can I trigger a sync for an ad server connection using its connection ID?
      - Will refreshing an ad server connection tell me if a sync is already running?
      instructions:
      - text: Refresh ad server connection {esaId}.
        slots:
          esaId: path.esaId
      - text: Start sync runs on connection {esaId}.
        slots:
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/capabilities/{capability}/recheck'].post
  update:
    x-apievangelist-phrasing:
      intent: Re-check an ad server reporting or forecasting capability
      effect: write
      questions:
      - My ad server vendor just enabled reporting access — how do I recheck it?
      - Will rechecking a forecasting capability resume a paused sync?
      instructions:
      - text: Re-check the {capability} capability on connection {esaId}.
        slots:
          capability: path.capability
          esaId: path.esaId
      - text: Verify {capability} is now live for ad server {esaId}.
        slots:
          capability: path.capability
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/deactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Deactivate an ad server by connection ID
      effect: destructive
      questions:
      - Can I deactivate an ad server connection by its connection ID and re-provision later?
      - Is deactivating an ad server connection reversible?
      instructions:
      - text: Deactivate ad server connection {esaId}.
        slots:
          esaId: path.esaId
      - text: Soft-delete the ad server with connection ID {esaId}.
        slots:
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/reactivate'].post
  update:
    x-apievangelist-phrasing:
      intent: Reactivate an ad server by connection ID
      effect: write
      questions:
      - How do I bring back a deactivated ad server connection using its connection ID?
      - What should I do if reactivation reports TENANT_NOT_FOUND?
      instructions:
      - text: Reactivate ad server connection {esaId}.
        slots:
          esaId: path.esaId
      - text: Re-enable connection {esaId}.
        slots:
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/status'].get
  update:
    x-apievangelist-phrasing:
      intent: Get ad server health by connection ID
      effect: read
      questions:
      - What is the operational snapshot for an ad server connection ID?
      - Can I see webhooks, workflows and setup tasks for an ad server connection?
      instructions:
      - text: Get the status of ad server connection {esaId}.
        slots:
          esaId: path.esaId
      - text: Show connection {esaId} status with sync history {includeSyncHistory}.
        slots:
          esaId: path.esaId
          includeSyncHistory: query.includeSyncHistory
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/sync-history'].get
  update:
    x-apievangelist-phrasing:
      intent: List sync runs by connection ID
      effect: read
      questions:
      - Can I page through historical syncs for an ad server connection ID?
      - Which sync types have run on an ad server connection?
      instructions:
      - text: List sync history for ad server connection {esaId}.
        slots:
          esaId: path.esaId
      - text: Show the last {limit} sync runs on connection {esaId}.
        slots:
          limit: query.limit
          esaId: path.esaId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/esa/{esaId}/launch'].post
  update:
    x-apievangelist-phrasing:
      intent: Open the admin UI for an ad server connection
      effect: write
      questions:
      - Can I get a one-time sign-in link to the admin UI for an ad server connection ID?
      - Can the admin launch link for a connection open on a specific page?
      instructions:
      - text: Mint a launch URL for ad server connection {esaId}.
        slots:
          esaId: path.esaId
      - text: Give me an admin link for connection {esaId} landing on {path}.
        slots:
          esaId: path.esaId
          path: requestBody.path
      method: generated
      generated: '2026-10-01'
- target: $.paths['/operating-instructions'].get
  update:
    x-apievangelist-phrasing:
      intent: List operating-instructions versions
      effect: read
      questions:
      - Which versions of my storefront's operating instructions exist?
      - Which operating-instructions version is active right now among all versions?
      instructions:
      - text: List all my operating-instructions versions.
      - text: Show the history of operating instructions, newest first.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/operating-instructions'].post
  update:
    x-apievangelist-phrasing:
      intent: Write a new operating-instructions version
      effect: write
      questions:
      - Does a new operating-instructions version go live automatically?
      - Can I create operating instructions and activate them in one call?
      instructions:
      - text: Create a new operating-instructions version with content {content}.
        slots:
          content: requestBody.content
      - text: Write operating instructions {content} and set activate to {activate}.
        slots:
          content: requestBody.content
          activate: requestBody.activate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/operating-instructions/active'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the active operating instructions
      effect: read
      questions:
      - What operating instructions is my merchandising agent following right now?
      - Have I activated any operating instructions yet?
      instructions:
      - text: Show my active operating instructions.
      - text: Get the operating-instructions version currently in use.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/operating-instructions/{version}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an operating-instructions version
      effect: read
      questions:
      - Can I read an older operating-instructions version by number?
      - What did operating instructions say in a past version?
      instructions:
      - text: Show operating-instructions version {version}.
        slots:
          version: path.version
      - text: Fetch operating instructions number {version}.
        slots:
          version: path.version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/operating-instructions/{version}/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate an operating-instructions version
      effect: write
      questions:
      - How do I roll back to a previous version of my operating instructions?
      - Which compositions use a newly activated operating-instructions version?
      instructions:
      - text: Activate operating-instructions version {version}.
        slots:
          version: path.version
      - text: Switch my storefront to operating instructions version {version}.
        slots:
          version: path.version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/acceptance-policy'].get
  update:
    x-apievangelist-phrasing:
      intent: List acceptance-policy versions
      effect: read
      questions:
      - Which acceptance-policy versions have I written?
      - Can I see which acceptance policy version is flagged active in the full list?
      instructions:
      - text: List all acceptance-policy versions.
      - text: Show my acceptance policy history, newest first.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/acceptance-policy'].post
  update:
    x-apievangelist-phrasing:
      intent: Write a new acceptance-policy version
      effect: write
      questions:
      - Can I author a new acceptance policy and make it active at the same time?
      - Are acceptance-policy versions editable after I create them?
      instructions:
      - text: Create an acceptance policy with content {content}.
        slots:
          content: requestBody.content
      - text: Write acceptance policy {content} and activate it {activate}.
        slots:
          content: requestBody.content
          activate: requestBody.activate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/acceptance-policy/active'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the active acceptance policy
      effect: read
      questions:
      - Which acceptance policy do my creative and media-buy approvals use right now?
      - Is any acceptance policy active on my storefront?
      instructions:
      - text: Show my active acceptance policy.
      - text: Get the acceptance policy approvals are using.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/acceptance-policy/{version}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an acceptance-policy version
      effect: read
      questions:
      - Can I read a specific acceptance-policy version by number?
      - What did an earlier acceptance policy allow?
      instructions:
      - text: Show acceptance-policy version {version}.
        slots:
          version: path.version
      - text: Fetch acceptance policy number {version}.
        slots:
          version: path.version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/acceptance-policy/{version}/activate'].post
  update:
    x-apievangelist-phrasing:
      intent: Activate an acceptance-policy version
      effect: write
      questions:
      - How do I switch approval workflows to a different acceptance policy version?
      - Can I revert to an older acceptance policy?
      instructions:
      - text: Activate acceptance-policy version {version}.
        slots:
          version: path.version
      - text: Make acceptance policy {version} the one approvals use.
        slots:
          version: path.version
      method: generated
      generated: '2026-10-01'
- target: $.paths['/learned-default-posture'].put
  update:
    x-apievangelist-phrasing:
      intent: Pin or clear the learned negotiation posture
      effect: write
      questions:
      - Can I pin a default negotiation posture for the merchandising agent?
      - When does the merchandising agent fall back to the learned default posture?
      instructions:
      - text: Pin {posture} as my storefront's learned default posture.
        slots:
          posture: requestBody.posture
      - text: Set the learned default negotiation posture to {posture}, or null to clear it.
        slots:
          posture: requestBody.posture
      method: generated
      generated: '2026-10-01'
- target: $.paths['/buyer-instructions'].get
  update:
    x-apievangelist-phrasing:
      intent: List buyer-instructions rows
      effect: read
      questions:
      - What buyer-specific discounts and instructions have I configured?
      - Which operator and brand pairs have buyer instructions?
      instructions:
      - text: List all my buyer-instructions rows.
      - text: Show every buyer instruction on the storefront.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/buyer-instructions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add buyer-specific instructions
      effect: write
      questions:
      - Can I give a specific agency and brand a discount limited to certain countries?
      - What happens if I create buyer instructions for a pair that already exists?
      instructions:
      - text: Give operator {operatorDomain} buying for {brandDomain} a {discountPercent}% discount in {countries} with notes {notes}.
        slots:
          operatorDomain: requestBody.operatorDomain
          brandDomain: requestBody.brandDomain
          discountPercent: requestBody.discountPercent
          countries: requestBody.countries
          notes: requestBody.notes
      - text: 'Create buyer instructions for {brandDomain} via {operatorDomain}: {discountPercent}% off, countries {countries}, note {notes}.'
        slots:
          brandDomain: requestBody.brandDomain
          operatorDomain: requestBody.operatorDomain
          discountPercent: requestBody.discountPercent
          countries: requestBody.countries
          notes: requestBody.notes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/buyer-instructions/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a buyer-instructions row
      effect: destructive
      questions:
      - Can I remove buyer-specific instructions I no longer want?
      - How do I change the brand on buyer instructions if scope is immutable?
      instructions:
      - text: Delete buyer-instructions row {id}.
        slots:
          id: path.id
      - text: Remove buyer instruction {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/buyer-instructions/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a buyer-instructions row
      effect: write
      questions:
      - Can I change the discount on existing buyer instructions?
      - Which buyer-instruction fields can I edit after creating it?
      instructions:
      - text: Change the discount on buyer instruction {id} to {discountPercent}%.
        slots:
          id: path.id
          discountPercent: requestBody.discountPercent
      - text: Update buyer instruction {id} countries to {countries}.
        slots:
          id: path.id
          countries: requestBody.countries
      method: generated
      generated: '2026-10-01'
- target: $.paths['/house-discounts'].get
  update:
    x-apievangelist-phrasing:
      intent: List rate-card discounts
      effect: read
      questions:
      - Which rate-card discounts have I set for brands and operators?
      - What house discounts are configured on my storefront?
      instructions:
      - text: List my rate-card discounts.
      - text: Show every brand and operator house discount.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/house-discounts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a rate-card discount
      effect: write
      questions:
      - Can I set a rate-card discount for a parent company that also covers its sub-brands?
      - Can I key a house discount to an operator instead of a brand?
      instructions:
      - text: Create a {discountPercent}% {scope} rate-card discount for {houseDomain} with note {notes}.
        slots:
          discountPercent: requestBody.discountPercent
          scope: requestBody.scope
          houseDomain: requestBody.houseDomain
          notes: requestBody.notes
      - text: Add a house discount of {discountPercent}% for {houseDomain} as a {scope}, noting {notes}.
        slots:
          discountPercent: requestBody.discountPercent
          houseDomain: requestBody.houseDomain
          scope: requestBody.scope
          notes: requestBody.notes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/house-discounts/resolve'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview a domain's corporate parent
      effect: read
      questions:
      - Which parent company would a discount for this brand domain resolve to?
      - Can I check a domain's corporate hierarchy before saving a discount?
      instructions:
      - text: Resolve {domain} up its corporate hierarchy.
        slots:
          domain: query.domain
      - text: Preview which house a discount for {domain} would key to.
        slots:
          domain: query.domain
      method: generated
      generated: '2026-10-01'
- target: $.paths['/house-discounts/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a rate-card discount
      effect: destructive
      questions:
      - Can I remove a rate-card discount I set for a house?
      - Is deleting the only way to change a house discount's scope?
      instructions:
      - text: Delete rate-card discount {id}.
        slots:
          id: path.id
      - text: Remove house discount {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/house-discounts/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a rate-card discount
      effect: write
      questions:
      - Can I change the percentage on an existing house discount?
      - Which fields on a rate-card discount can I still edit?
      instructions:
      - text: Set rate-card discount {id} to {discountPercent}%.
        slots:
          id: path.id
          discountPercent: requestBody.discountPercent
      - text: Update the notes on house discount {id} to {notes}.
        slots:
          id: path.id
          notes: requestBody.notes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/buyer-auto-approvals'].get
  update:
    x-apievangelist-phrasing:
      intent: List per-buyer auto-approve overrides
      effect: read
      questions:
      - Which buyers have media-buy auto-approve turned on?
      - Can I see buyers whose auto-approve override is disabled too?
      instructions:
      - text: List my per-buyer media-buy auto-approve settings.
      - text: Show which trusted buyers skip media-buy review.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/buyer-auto-approvals/{buyerCustomerId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Turn auto-approve on or off for a buyer
      effect: write
      questions:
      - Can I let a trusted buyer's media buys skip human review?
      - Does buyer auto-approve also apply to their creatives?
      instructions:
      - text: Set auto-approve for buyer {buyerCustomerId} to {enabled}.
        slots:
          buyerCustomerId: path.buyerCustomerId
          enabled: requestBody.enabled
      - text: Enable media-buy auto-approval for buyer {buyerCustomerId} with enabled {enabled} because {reason}.
        slots:
          buyerCustomerId: path.buyerCustomerId
          enabled: requestBody.enabled
          reason: requestBody.reason
      method: generated
      generated: '2026-10-01'
- target: $.paths['/simulator/scenarios'].get
  update:
    x-apievangelist-phrasing:
      intent: List merchandising simulator scenarios
      effect: read
      questions:
      - Which merchandising simulator scenarios have I saved?
      - Are my older simulator scenarios still runnable after 30 days?
      instructions:
      - text: List my merchandising simulation scenarios.
      - text: Show {limit} simulator scenarios from offset {offset}.
        slots:
          limit: query.limit
          offset: query.offset
      method: generated
      generated: '2026-10-01'
- target: $.paths['/simulator/scenarios'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a merchandising simulator scenario
      effect: write
      questions:
      - Can I build a simulation scenario from a past decision my storefront made?
      - Can I start a simulator scenario from my own brief?
      instructions:
      - text: Create a simulator scenario titled {title} from source {source}.
        slots:
          title: requestBody.title
          source: requestBody.source
      - text: Start a merchandising simulation {title} using {source} on inventory source {sourceId}.
        slots:
          title: requestBody.title
          source: requestBody.source
          sourceId: requestBody.sourceId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/simulator/scenarios/{scenarioId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a merchandising simulator scenario
      effect: read
      questions:
      - What revisions and variants does a simulator scenario contain?
      - Can I open one simulation scenario to review its history?
      instructions:
      - text: Show simulator scenario {scenarioId}.
        slots:
          scenarioId: path.scenarioId
      - text: Get every revision and variant of scenario {scenarioId}.
        slots:
          scenarioId: path.scenarioId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/simulator/scenarios/{scenarioId}/revisions'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a revision to a simulator scenario
      effect: write
      questions:
      - Can I recapture a simulator scenario without overwriting earlier evidence?
      - Does a new scenario revision get its own replay window?
      instructions:
      - text: Append a revision titled {title} to scenario {scenarioId} from {source}.
        slots:
          title: requestBody.title
          scenarioId: path.scenarioId
          source: requestBody.source
      - text: Capture a fresh revision {title} of simulation {scenarioId} using source {source}.
        slots:
          title: requestBody.title
          scenarioId: path.scenarioId
          source: requestBody.source
      method: generated
      generated: '2026-10-01'
- target: $.paths['/simulator/scenarios/{scenarioId}/revisions/{revisionId}/variants'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a what-if variant to a simulation
      effect: write
      questions:
      - Can I test a different pricing or posture in the simulator without changing my live storefront?
      - How many counterfactual variants can one simulation revision hold?
      instructions:
      - text: Add variant {label} with overrides {overrides} to revision {revisionId} of scenario {scenarioId}.
        slots:
          label: requestBody.label
          overrides: requestBody.overrides
          revisionId: path.revisionId
          scenarioId: path.scenarioId
      - text: Create a what-if {label} on scenario {scenarioId} revision {revisionId} using {overrides}.
        slots:
          label: requestBody.label
          scenarioId: path.scenarioId
          revisionId: path.revisionId
          overrides: requestBody.overrides
      method: generated
      generated: '2026-10-01'
- target: $.paths['/simulator/scenarios/{scenarioId}/revisions/{revisionId}/variants/{variantId}/executions'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a merchandising simulation variant
      effect: write
      questions:
      - How do I run a simulator variant through the merchandising engine?
      - Does running a simulation variant change my live storefront controls?
      instructions:
      - text: Execute variant {variantId} of revision {revisionId} in scenario {scenarioId}.
        slots:
          variantId: path.variantId
          revisionId: path.revisionId
          scenarioId: path.scenarioId
      - text: Run simulation variant {variantId} on scenario {scenarioId}, revision {revisionId}.
        slots:
          variantId: path.variantId
          scenarioId: path.scenarioId
          revisionId: path.revisionId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/intelligence-runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List storefront intelligence runs
      effect: read
      questions:
      - What briefs has my merchandising agent processed recently?
      - Can I filter intelligence runs by disposition or commercial result?
      instructions:
      - text: List my latest intelligence runs.
      - text: Show intelligence runs with disposition {disposition}.
        slots:
          disposition: query.disposition
      - text: Search intelligence runs for {q}.
        slots:
          q: query.q
      method: generated
      generated: '2026-10-01'
- target: $.paths['/intelligence-runs/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one intelligence run
      effect: read
      questions:
      - What prompt and LLM output produced a specific intelligence run?
      - Which products did an intelligence run compose?
      instructions:
      - text: Show intelligence run {id} with its full prompt and output.
        slots:
          id: path.id
      - text: Get the rationale and composed products for run {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/intelligence-runs/{id}/decision-record'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the seller decision record for a run
      effect: read
      questions:
      - Why did my storefront respond to a buyer ask the way it did?
      - Can I see the approval and commercial outcome chronology for one run?
      instructions:
      - text: Show the seller decision record for run {id}.
        slots:
          id: path.id
      - text: Get the decision chronology for intelligence run {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/intelligence-runs/{id}/label'].put
  update:
    x-apievangelist-phrasing:
      intent: Label an intelligence run for evaluation
      effect: write
      questions:
      - Can I grade an intelligence run as good or bad for evals?
      - Does labeling a run replace an existing evaluator label?
      instructions:
      - text: Label intelligence run {id} with {label}.
        slots:
          id: path.id
          label: requestBody.label
      - text: Attach evaluator verdict {label} to run {id}.
        slots:
          label: requestBody.label
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demand-inbox'].get
  update:
    x-apievangelist-phrasing:
      intent: View the demand inbox ledger
      effect: read
      questions:
      - What briefs, proposals and results are in my demand inbox?
      - Can I see win metrics computed from my demand inbox rows?
      instructions:
      - text: Show my demand inbox.
      - text: Get {take} demand inbox rows skipping {skip}.
        slots:
          take: query.take
          skip: query.skip
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demand-inbox/{runId}/ledger'].put
  update:
    x-apievangelist-phrasing:
      intent: Grade a demand inbox row
      effect: write
      questions:
      - Can I give a proposal an A to F grade and record buyer feedback?
      - Can I note whether an agent or a human led a deal?
      instructions:
      - text: Grade demand inbox run {runId} as {grade}.
        slots:
          runId: path.runId
          grade: requestBody.grade
      - text: Record buyer feedback {feedback} on inbox row {runId}, led by {ledBy}.
        slots:
          feedback: requestBody.feedback
          runId: path.runId
          ledBy: requestBody.ledBy
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demand-inbox/{runId}/exchange'].get
  update:
    x-apievangelist-phrasing:
      intent: View a demand exchange's proposal passes
      effect: read
      questions:
      - What happened across each proposal pass for one buyer brief?
      - Can I inspect the pricing and product allocation of each pass in a deal?
      instructions:
      - text: Show the full exchange for demand run {runId}.
        slots:
          runId: path.runId
      - text: Get the proposal passes and pricing for exchange {runId}.
        slots:
          runId: path.runId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demand-inbox/{runId}/exchange/revisions'].post
  update:
    x-apievangelist-phrasing:
      intent: Draft a revised proposal on a live exchange
      effect: write
      questions:
      - Can I re-price a live proposal by drafting a revision with new overrides?
      - Does composing an exchange revision send it to the buyer right away?
      instructions:
      - text: Compose a draft revision on exchange {runId} with overrides {overrides}.
        slots:
          runId: path.runId
          overrides: requestBody.overrides
      - text: Draft a new proposal pass for run {runId} using {overrides}.
        slots:
          runId: path.runId
          overrides: requestBody.overrides
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demand-inbox/{runId}/exchange/revisions/{revisionId}/submit'].post
  update:
    x-apievangelist-phrasing:
      intent: Submit a proposal revision for approval
      effect: write
      questions:
      - How do I send a drafted exchange revision for approval?
      - Will an auto-approve override clear my submitted revision immediately?
      instructions:
      - text: Submit revision {revisionId} on exchange {runId} at generation {expectedSubmissionGeneration}.
        slots:
          revisionId: path.revisionId
          runId: path.runId
          expectedSubmissionGeneration: requestBody.expectedSubmissionGeneration
      - text: Send draft {revisionId} of run {runId} for approval, expecting generation {expectedSubmissionGeneration}.
        slots:
          revisionId: path.revisionId
          runId: path.runId
          expectedSubmissionGeneration: requestBody.expectedSubmissionGeneration
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demand-inbox/{runId}/exchange/revisions/{revisionId}/decision'].put
  update:
    x-apievangelist-phrasing:
      intent: Approve or reject a proposal revision
      effect: write
      questions:
      - Can the person who drafted a proposal revision also approve it?
      - Can I withdraw my own submitted exchange revision?
      instructions:
      - text: Mark revision {revisionId} on exchange {runId} as {decision} at generation {expectedSubmissionGeneration}.
        slots:
          revisionId: path.revisionId
          runId: path.runId
          decision: requestBody.decision
          expectedSubmissionGeneration: requestBody.expectedSubmissionGeneration
      - text: Reject exchange revision {revisionId} for run {runId} with notes {notes}, generation {expectedSubmissionGeneration}, decision {decision}.
        slots:
          revisionId: path.revisionId
          runId: path.runId
          notes: requestBody.notes
          expectedSubmissionGeneration: requestBody.expectedSubmissionGeneration
          decision: requestBody.decision
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demand-inbox/{runId}/exchange/revisions/{revisionId}/amend'].post
  update:
    x-apievangelist-phrasing:
      intent: Amend a draft proposal revision in place
      effect: write
      questions:
      - Can I fix a rejected exchange revision instead of starting a new one?
      - What happens to a pending approval if I amend the draft?
      instructions:
      - text: Amend revision {revisionId} on exchange {runId} with overrides {overrides}.
        slots:
          revisionId: path.revisionId
          runId: path.runId
          overrides: requestBody.overrides
      - text: Re-run draft {revisionId} of run {runId} in place using {overrides}.
        slots:
          revisionId: path.revisionId
          runId: path.runId
          overrides: requestBody.overrides
      method: generated
      generated: '2026-10-01'
- target: $.paths['/demand-inbox/{runId}/exchange/revisions/{revisionId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Discard a draft proposal revision
      effect: destructive
      questions:
      - Can I throw away a draft exchange revision I don't want?
      - Does a discarded revision still count against the adjustment limit?
      instructions:
      - text: Discard draft revision {revisionId} on exchange {runId}.
        slots:
          revisionId: path.revisionId
          runId: path.runId
      - text: Delete the unsubmitted revision {revisionId} for run {runId}.
        slots:
          revisionId: path.revisionId
          runId: path.runId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/brief-artifacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List received buyer brief artifacts
      effect: read
      questions:
      - Which get_products briefs has my storefront received from buyers?
      - Can I page through the stored brief artifacts?
      instructions:
      - text: List the brief artifacts my storefront received.
      - text: Show {take} brief artifacts skipping {skip}.
        slots:
          take: query.take
          skip: query.skip
      method: generated
      generated: '2026-10-01'
- target: $.paths['/brief-artifacts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a buyer brief artifact
      effect: read
      questions:
      - What exact request did a buyer send in one brief?
      - Was a brief artifact's payload kept or truncated for size?
      instructions:
      - text: Show brief artifact {id} with its payload.
        slots:
          id: path.id
      - text: Get the redaction manifest for brief {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/proposal-artifacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List proposal artifacts sent to buyers
      effect: read
      questions:
      - What proposals has my storefront sent back to buyers?
      - Can I see every proposal version that answered one brief?
      instructions:
      - text: List my proposal artifacts.
      - text: Show every proposal answering brief {briefArtifactId}.
        slots:
          briefArtifactId: query.briefArtifactId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/proposal-artifacts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a proposal artifact
      effect: read
      questions:
      - What exactly did my storefront propose in one response?
      - Can I see the product snapshots referenced by a proposal?
      instructions:
      - text: Show proposal artifact {id}.
        slots:
          id: path.id
      - text: Get the response envelope and products for proposal {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/seller-analytics'].get
  update:
    x-apievangelist-phrasing:
      intent: See win rate by negotiation posture
      effect: read
      questions:
      - Which negotiation posture wins the most deals for my storefront?
      - How often does my agent follow the recommended posture?
      instructions:
      - text: Show seller analytics by negotiation posture.
      - text: Roll up posture conversion over the last {limit} runs.
        slots:
          limit: query.limit
      method: generated
      generated: '2026-10-01'
- target: $.paths['/approval-routing'].get
  update:
    x-apievangelist-phrasing:
      intent: Get approval routing settings
      effect: read
      questions:
      - Who gets notified when a media buy or creative needs approval?
      - What are my approval reminder and escalation SLAs?
      instructions:
      - text: Show my storefront approval routing.
      - text: Get the primary and fallback approvers for media buys and creatives.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/approval-routing/{kind}'].put
  update:
    x-apievangelist-phrasing:
      intent: Set approval routing for buys or creatives
      effect: write
      questions:
      - Can I route creative approvals to specific users with a fallback group?
      - How do I set when approvals send reminders and escalate?
      instructions:
      - text: Route {kind} approvals over {primaryChannels}, falling back to {fallbackChannels}.
        slots:
          kind: path.kind
          primaryChannels: requestBody.primaryChannels
          fallbackChannels: requestBody.fallbackChannels
      - text: For {kind} approvals, remind after {reminderAfterMinutes} min and escalate after {escalateAfterMinutes} min.
        slots:
          kind: path.kind
          reminderAfterMinutes: requestBody.reminderAfterMinutes
          escalateAfterMinutes: requestBody.escalateAfterMinutes
      - text: Send {kind} approvals to users {primaryUserIds} first.
        slots:
          kind: path.kind
          primaryUserIds: requestBody.primaryUserIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/approval-routing/work-items/{workItemId}/assignee'].put
  update:
    x-apievangelist-phrasing:
      intent: Reassign an approval task
      effect: write
      questions:
      - Can I move a pending approval to a different eligible reviewer?
      - Does reassigning approval work give an admin approval rights?
      instructions:
      - text: Reassign approval work item {workItemId} to user {userId}.
        slots:
          workItemId: path.workItemId
          userId: requestBody.userId
      - text: Hand approval task {workItemId} over to {userId}.
        slots:
          workItemId: path.workItemId
          userId: requestBody.userId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/media-buy-approvals'].get
  update:
    x-apievangelist-phrasing:
      intent: List the media-buy approval queue
      effect: read
      questions:
      - Which media buys are waiting for my approval?
      - Can I see media buys I already approved, rejected or revoked?
      instructions:
      - text: List pending media-buy approvals.
      - text: Show media-buy approvals with status {status}.
        slots:
          status: query.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/media-buy-approvals/{mediaBuyId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one media-buy approval entry
      effect: read
      questions:
      - What did the buyer submit in a specific media buy awaiting approval?
      - Has a decision been recorded on a given media buy approval?
      instructions:
      - text: Show the approval entry for media buy {mediaBuyId}.
        slots:
          mediaBuyId: path.mediaBuyId
      - text: Get the submitted payload and status of buy {mediaBuyId}.
        slots:
          mediaBuyId: path.mediaBuyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/media-buy-approvals/{mediaBuyId}/decide'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve or reject a pending media buy
      effect: write
      questions:
      - How do I approve a media buy so it gets forwarded upstream?
      - Can I decide on a media buy that was already approved?
      instructions:
      - text: Set media buy {mediaBuyId} to {status}.
        slots:
          mediaBuyId: path.mediaBuyId
          status: requestBody.status
      - text: Reject media buy {mediaBuyId} with status {status} and note {reviewerNotes}.
        slots:
          mediaBuyId: path.mediaBuyId
          status: requestBody.status
          reviewerNotes: requestBody.reviewerNotes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/media-buy-approvals/{mediaBuyId}/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Check a media buy against acceptance policy
      effect: read
      questions:
      - Is this pending media buy on policy or does it need a human?
      - When will the evaluator recommend auto-approving a media buy?
      instructions:
      - text: Evaluate media buy {mediaBuyId} against my acceptance policy.
        slots:
          mediaBuyId: path.mediaBuyId
      - text: Classify whether buy {mediaBuyId} needs human approval.
        slots:
          mediaBuyId: path.mediaBuyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/media-buy-approvals/{mediaBuyId}/retry-forward'].post
  update:
    x-apievangelist-phrasing:
      intent: Retry forwarding an approved media buy
      effect: write
      questions:
      - My approved media buy never reached the source — can I resend it?
      - Will retrying a forward double-book the buy?
      instructions:
      - text: Retry forwarding approved media buy {mediaBuyId}.
        slots:
          mediaBuyId: path.mediaBuyId
      - text: Mark the forward of buy {mediaBuyId} terminal with forceTerminal {forceTerminal} because {reason}.
        slots:
          mediaBuyId: path.mediaBuyId
          forceTerminal: requestBody.forceTerminal
          reason: requestBody.reason
      method: generated
      generated: '2026-10-01'
- target: $.paths['/media-buys'].get
  update:
    x-apievangelist-phrasing:
      intent: List all media buys on the storefront
      effect: read
      questions:
      - Which media buys have flights starting in the next two days?
      - Can I filter all my media buys by buyer or inventory source?
      instructions:
      - text: List every media buy on my storefront.
      - text: Show media buys from buyer {buyerCustomerId} on source {sourceId}.
        slots:
          buyerCustomerId: query.buyerCustomerId
          sourceId: query.sourceId
      - text: Find media buys with flights starting between {flightStartFrom} and {flightStartTo}.
        slots:
          flightStartFrom: query.flightStartFrom
          flightStartTo: query.flightStartTo
      method: generated
      generated: '2026-10-01'
- target: $.paths['/media-buys/{mediaBuyId}/timeline'].get
  update:
    x-apievangelist-phrasing:
      intent: Trace a media buy's timeline
      effect: read
      questions:
      - Where is a media buy stuck between screening, forwarding and delivery?
      - Can I see each stage and source leg of a media buy?
      instructions:
      - text: Show the exchange timeline for media buy {mediaBuyId}.
        slots:
          mediaBuyId: path.mediaBuyId
      - text: Trace the stages of buy {mediaBuyId}.
        slots:
          mediaBuyId: path.mediaBuyId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/pending-operations'].get
  update:
    x-apievangelist-phrasing:
      intent: List everything waiting on someone
      effect: read
      questions:
      - What is waiting on me across buys, creatives and failed forwards?
      - Which failed forwards can I retry versus escalate?
      instructions:
      - text: Show everything pending on my storefront.
      - text: List pending approvals, creative reviews and failed forwards together.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/gam-cleanups/{operationId}'].post
  update:
    x-apievangelist-phrasing:
      intent: Clean up a failed GAM order
      effect: destructive
      questions:
      - Can the sales agent archive a failed Google Ad Manager order for me?
      - How do I record that I cleaned up a failed GAM order myself?
      instructions:
      - text: Archive the failed GAM order for cleanup operation {operationId}.
        slots:
          operationId: path.operationId
      - text: Resolve failed GAM order cleanup {operationId}.
        slots:
          operationId: path.operationId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/test-runs'].get
  update:
    x-apievangelist-phrasing:
      intent: List recent sandbox agent test runs
      effect: read
      questions:
      - What sandbox test runs have been run against my storefront's agents?
      - Can I look up one sandbox test run by its run ID?
      instructions:
      - text: List my recent sandbox test runs.
      - text: Show sandbox test run {runUid}.
        slots:
          runUid: query.runUid
      method: generated
      generated: '2026-10-01'
- target: $.paths['/test-campaigns/plan'].post
  update:
    x-apievangelist-phrasing:
      intent: Plan a sandbox test campaign
      effect: read
      questions:
      - Can I check a source's readiness for a no-spend test campaign before running it?
      - How do I get the plan token needed to run a sandbox campaign?
      instructions:
      - text: Plan a sandbox test campaign for an inventory source.
      - text: Inspect product candidates for a no-spend test campaign.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/test-campaigns/execute'].post
  update:
    x-apievangelist-phrasing:
      intent: Run a confirmed sandbox test campaign
      effect: write
      questions:
      - How do I launch the sandbox test campaign I planned?
      - Can I change the budget when executing a planned test campaign?
      instructions:
      - text: Execute the sandbox test campaign with plan token {planToken}.
        slots:
          planToken: requestBody.planToken
      - text: Run planned test campaign {planToken}.
        slots:
          planToken: requestBody.planToken
      method: generated
      generated: '2026-10-01'
- target: $.paths['/creative-reviews'].get
  update:
    x-apievangelist-phrasing:
      intent: List the creative review queue
      effect: read
      questions:
      - Which buyer creatives are waiting for my review?
      - Can I list creatives I've already approved or rejected?
      instructions:
      - text: List pending creative reviews.
      - text: Show creative reviews with status {status}.
        slots:
          status: query.status
      method: generated
      generated: '2026-10-01'
- target: $.paths['/creative-reviews/{creativeId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a creative review
      effect: read
      questions:
      - What is the review status of one buyer creative?
      - Can I look up a creative review by its creative ID?
      instructions:
      - text: Show creative review {creativeId}.
        slots:
          creativeId: path.creativeId
      - text: Get the review row for creative {creativeId}.
        slots:
          creativeId: path.creativeId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/creative-reviews/{creativeId}/decide'].post
  update:
    x-apievangelist-phrasing:
      intent: Approve or reject a creative
      effect: write
      questions:
      - How do I approve a buyer's creative?
      - Can I revoke a creative that's already approved through the decide step?
      instructions:
      - text: Set creative {creativeId} to {status}.
        slots:
          creativeId: path.creativeId
          status: requestBody.status
      - text: Reject creative {creativeId} as {status} with notes {reviewer_notes}.
        slots:
          creativeId: path.creativeId
          status: requestBody.status
          reviewer_notes: requestBody.reviewer_notes
      method: generated
      generated: '2026-10-01'
- target: $.paths['/creative-reviews/{creativeId}/evaluate'].post
  update:
    x-apievangelist-phrasing:
      intent: Get an AI recommendation on a creative
      effect: read
      questions:
      - Can AI tell me whether a buyer creative fits my acceptance policy?
      - Can I ask the evaluator specific questions about a creative?
      instructions:
      - text: Evaluate creative {creativeId} with AI.
        slots:
          creativeId: path.creativeId
      - text: Check creative {creativeId} is for brand {expected_brand} and answer {questions}.
        slots:
          creativeId: path.creativeId
          expected_brand: requestBody.expected_brand
          questions: requestBody.questions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/publishers'].get
  update:
    x-apievangelist-phrasing:
      intent: List publisher domains
      effect: read
      questions:
      - Which publisher domains is my storefront associated with?
      - Are my publisher domains authorized in their adagents.json?
      instructions:
      - text: List my storefront's publisher domains.
      - text: Show publishers with their adagents.json authorization verdict.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/publishers'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace the full publisher list
      effect: write
      questions:
      - Can I upload my whole list of publisher domains at once?
      - What happens if one domain in a bulk publisher replace is invalid?
      instructions:
      - text: Replace my declared publishers with {publishers}.
        slots:
          publishers: requestBody.publishers
      - text: Overwrite the publisher domain list with {publishers}.
        slots:
          publishers: requestBody.publishers
      method: generated
      generated: '2026-10-01'
- target: $.paths['/publishers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a publisher domain
      effect: write
      questions:
      - Can I add a single publisher domain by pasting its URL?
      - How do I declare one more publisher on my storefront?
      instructions:
      - text: Add publisher domain {domain}.
        slots:
          domain: requestBody.domain
      - text: Declare {domain} as one of my publishers.
        slots:
          domain: requestBody.domain
      method: generated
      generated: '2026-10-01'
- target: $.paths['/property-roster'].get
  update:
    x-apievangelist-phrasing:
      intent: Get the property roster
      effect: read
      questions:
      - Which properties and collections are resolved under each of my publishers?
      - What is the authorization status of the properties in my roster?
      instructions:
      - text: Show my property roster.
      - text: Get every publisher's properties and authorization outcome.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/property-roster/properties'].post
  update:
    x-apievangelist-phrasing:
      intent: Declare a property under a publisher
      effect: write
      questions:
      - Can I add a property myself when the publisher's adagents.json doesn't list it?
      - What happens if the publisher later declares the same property?
      instructions:
      - text: Declare property {property} under publisher {domain}.
        slots:
          property: requestBody.property
          domain: requestBody.domain
      - text: Add a seller-declared property {property} to {domain}.
        slots:
          property: requestBody.property
          domain: requestBody.domain
      method: generated
      generated: '2026-10-01'
- target: $.paths['/property-roster/properties/{domain}/{propertyKey}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a declared roster property
      effect: destructive
      questions:
      - Can I remove a property I declared from the roster?
      - Why can't I remove a property that came from the publisher's adagents.json?
      instructions:
      - text: Remove property {propertyKey} from publisher {domain}.
        slots:
          propertyKey: path.propertyKey
          domain: path.domain
      - text: Delete my declared property {propertyKey} under {domain}.
        slots:
          propertyKey: path.propertyKey
          domain: path.domain
      method: generated
      generated: '2026-10-01'
- target: $.paths['/publishers/{domain}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Remove a publisher domain
      effect: destructive
      questions:
      - Can I remove a publisher domain I declared?
      - Why does removing a crawled publisher domain fail?
      instructions:
      - text: Remove publisher domain {domain}.
        slots:
          domain: path.domain
      - text: Drop {domain} from my declared publishers.
        slots:
          domain: path.domain
      method: generated
      generated: '2026-10-01'