# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Scope3 Buyer Measurement API
  version: 1.0.0
extends: openapi/scope3-measurement-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: 16
- target: $.paths['/advertisers/{advertiserId}/measurement-data/sync'].post
  update:
    x-apievangelist-phrasing:
      intent: Sync performance measurement data
      effect: write
      questions:
      - Can I send campaign performance data directly instead of using a conversions API?
      - What granularity can synced measurement data be keyed by?
      instructions:
      - text: Sync measurements {measurements} for advertiser {advertiserId}.
        slots:
          measurements: requestBody.measurements
          advertiserId: path.advertiserId
      - text: Push time-series performance data {measurements} to advertiser {advertiserId}.
        slots:
          measurements: requestBody.measurements
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/test-cohorts'].get
  update:
    x-apievangelist-phrasing:
      intent: List an advertiser's test cohorts
      effect: read
      questions:
      - Which test cohorts exist for my advertiser?
      - Can I list only active test cohorts, or filter by role?
      instructions:
      - text: List test cohorts for advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      - text: Show active test cohorts with role {role} for advertiser {advertiserId}.
        slots:
          role: query.role
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/test-cohorts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a measurement test cohort
      effect: write
      questions:
      - How do I set up a test cohort for incrementality measurement?
      - What definition does a new test cohort need?
      instructions:
      - text: Create test cohort {name} of type {cohortType} with definition {definition} for advertiser {advertiserId}.
        slots:
          name: requestBody.name
          cohortType: requestBody.cohortType
          definition: requestBody.definition
          advertiserId: path.advertiserId
      - text: Add a {cohortType} cohort named {name} defined as {definition} under advertiser {advertiserId}.
        slots:
          cohortType: requestBody.cohortType
          name: requestBody.name
          definition: requestBody.definition
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/test-cohorts/{cohortId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a test cohort
      effect: read
      questions:
      - Can I see the definition of one test cohort?
      - What is the estimated size of a specific cohort?
      instructions:
      - text: Get test cohort {cohortId}.
        slots:
          cohortId: path.cohortId
      - text: Show the details of cohort {cohortId}.
        slots:
          cohortId: path.cohortId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/test-cohorts/{cohortId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a test cohort
      effect: write
      questions:
      - Can I change a test cohort's definition after creating it?
      - Is it possible to rename a cohort or switch its role?
      instructions:
      - text: Rename test cohort {cohortId} to {name}.
        slots:
          cohortId: path.cohortId
          name: requestBody.name
      - text: Change the definition of cohort {cohortId} to {definition}.
        slots:
          cohortId: path.cohortId
          definition: requestBody.definition
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/test-cohorts/{cohortId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a test cohort
      effect: destructive
      questions:
      - Can I remove a test cohort I no longer use?
      - Is deleting a measurement cohort reversible?
      instructions:
      - text: Delete test cohort {cohortId}.
        slots:
          cohortId: path.cohortId
      - text: Remove cohort {cohortId} from measurement.
        slots:
          cohortId: path.cohortId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/measurement-config'].get
  update:
    x-apievangelist-phrasing:
      intent: Get an advertiser's measurement settings
      effect: read
      questions:
      - Is media mix modeling or brand lift enabled for my advertiser?
      - What measurement configuration is set on an advertiser?
      instructions:
      - text: Get the measurement configuration for advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      - text: Check if MMM is on for advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/measurement-config'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an advertiser's measurement settings
      effect: write
      questions:
      - How do I turn on brand lift measurement for an advertiser?
      - Can I enable MMM and pass its configuration?
      instructions:
      - text: 'Enable MMM for advertiser {advertiserId}: {mmmEnabled}.'
        slots:
          advertiserId: path.advertiserId
          mmmEnabled: requestBody.mmmEnabled
      - text: Set brand lift enabled to {brandLiftEnabled} on advertiser {advertiserId}.
        slots:
          brandLiftEnabled: requestBody.brandLiftEnabled
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/measurement-sources'].get
  update:
    x-apievangelist-phrasing:
      intent: List measurement sources
      effect: read
      questions:
      - Which measurement data sources are registered for my advertiser?
      - Can I filter measurement sources by outcome type?
      instructions:
      - text: List measurement sources for advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      - text: Show {outcomeType} measurement sources for advertiser {advertiserId}.
        slots:
          outcomeType: query.outcomeType
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/measurement-sources'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a measurement source
      effect: write
      questions:
      - How do I register an MMM or brand lift study as a data source?
      - What cadence and granularity does a measurement source need?
      instructions:
      - text: 'Register source {name} ({sourceKey}) by {provider} on advertiser {advertiserId}: {outcomeType}, {granularity}, {cadence}.'
        slots:
          name: requestBody.name
          sourceKey: requestBody.sourceKey
          provider: requestBody.provider
          advertiserId: path.advertiserId
          outcomeType: requestBody.outcomeType
          granularity: requestBody.granularity
          cadence: requestBody.cadence
      - text: Add a {cadence} {outcomeType} source {name} ({sourceKey}) by {provider} at {granularity} level to advertiser {advertiserId}.
        slots:
          cadence: requestBody.cadence
          outcomeType: requestBody.outcomeType
          name: requestBody.name
          sourceKey: requestBody.sourceKey
          provider: requestBody.provider
          granularity: requestBody.granularity
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/measurement-sources/{sourceId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a measurement source
      effect: read
      questions:
      - Can I see how one measurement source is configured?
      - What attribution settings does a particular data source use?
      instructions:
      - text: Get measurement source {sourceId} for advertiser {advertiserId}.
        slots:
          sourceId: path.sourceId
          advertiserId: path.advertiserId
      - text: Show the config of source {sourceId} on advertiser {advertiserId}.
        slots:
          sourceId: path.sourceId
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/measurement-sources/{sourceId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a measurement source
      effect: write
      questions:
      - Can I change the lag weeks or signal weight of a measurement source?
      - How do I pause a measurement source by changing its status?
      instructions:
      - text: Set the status of measurement source {sourceId} on advertiser {advertiserId} to {status}.
        slots:
          sourceId: path.sourceId
          advertiserId: path.advertiserId
          status: requestBody.status
      - text: Change signal weight of source {sourceId} for advertiser {advertiserId} to {signalWeight}.
        slots:
          sourceId: path.sourceId
          advertiserId: path.advertiserId
          signalWeight: requestBody.signalWeight
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/measurement-records'].get
  update:
    x-apievangelist-phrasing:
      intent: List uploaded measurement records
      effect: read
      questions:
      - Which outcome records have I uploaded for a date range?
      - Can I filter measurement records by geo?
      instructions:
      - text: List measurement records for advertiser {advertiserId}.
        slots:
          advertiserId: path.advertiserId
      - text: Show {outcomeType} records for advertiser {advertiserId} in geo {geo} from {startDate} to {endDate}.
        slots:
          outcomeType: query.outcomeType
          advertiserId: path.advertiserId
          geo: query.geo
          startDate: query.startDate
          endDate: query.endDate
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/measurement-records'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload outcome measurement records
      effect: write
      questions:
      - How do I upload sales or brand lift results for measurement?
      - Will re-uploading the same outcome window overwrite earlier records?
      instructions:
      - text: Upload outcome records {records} for advertiser {advertiserId}.
        slots:
          records: requestBody.records
          advertiserId: path.advertiserId
      - text: Upsert sales outcome records {records} to advertiser {advertiserId}.
        slots:
          records: requestBody.records
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/context-records'].post
  update:
    x-apievangelist-phrasing:
      intent: Upload context data like promos or weather
      effect: write
      questions:
      - Can I feed promotions or weather into measurement analysis?
      - Where do I upload external context data such as competitor activity?
      instructions:
      - text: Upload context records {records} for advertiser {advertiserId}.
        slots:
          records: requestBody.records
          advertiserId: path.advertiserId
      - text: Add promo and weather context {records} to advertiser {advertiserId}.
        slots:
          records: requestBody.records
          advertiserId: path.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/advertisers/{advertiserId}/measurement-freshness'].get
  update:
    x-apievangelist-phrasing:
      intent: Check gaps in measurement data
      effect: read
      questions:
      - Is any measurement data missing for my flight dates?
      - Which geos have stale measurement coverage?
      instructions:
      - text: Check measurement freshness for advertiser {advertiserId} from {flightStart} in geos {geos}.
        slots:
          advertiserId: path.advertiserId
          flightStart: query.flightStart
          geos: query.geos
      - text: Find measurement gaps for advertiser {advertiserId} between {flightStart} and {flightEnd} across {geos}.
        slots:
          advertiserId: path.advertiserId
          flightStart: query.flightStart
          flightEnd: query.flightEnd
          geos: query.geos
      method: generated
      generated: '2026-10-01'