# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Scope3 Signals API
  version: 1.0.0
extends: openapi/scope3-signals-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: 7
- target: $.paths['/signals/saved_list/{saved_list_id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get media quality signals for a saved domain list
      effect: read
      questions:
      - What are the media quality scores for every domain in one of my saved lists?
      - Can I page through domain-level quality signals for a property list?
      instructions:
      - text: Get media quality signals for saved list {saved_list_id}.
        slots:
          saved_list_id: path.saved_list_id
      - text: Show page {page} of domain quality signals for saved list {saved_list_id}.
        slots:
          page: query.page
          saved_list_id: path.saved_list_id
      method: generated
      generated: '2026-10-01'
- target: $.paths['/signals'].get
  update:
    x-apievangelist-phrasing:
      intent: List my registered signals
      effect: read
      questions:
      - Which targeting signals have I registered, and which are live?
      - Can I list signals for one advertiser or one signal agent?
      instructions:
      - text: List my registered signals.
      - text: List live signals for advertiser {advertiser_id}.
        slots:
          advertiser_id: query.advertiserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/signals'].post
  update:
    x-apievangelist-phrasing:
      intent: Register a new signal
      effect: write
      questions:
      - What do I need to register a new targeting signal?
      - Can I set which regions and accounts get access when registering a signal?
      instructions:
      - text: Register signal {signal_id} named {name} with key type {key_type}.
        slots:
          signal_id: requestBody.signalId
          name: requestBody.name
          key_type: requestBody.keyType
      - text: Create signal {signal_id} called {name}, key type {key_type}, available in {regions}.
        slots:
          signal_id: requestBody.signalId
          name: requestBody.name
          key_type: requestBody.keyType
          regions: requestBody.regions
      method: generated
      generated: '2026-10-01'
- target: $.paths['/signals/{signalId}'].get
  update:
    x-apievangelist-phrasing:
      intent: View one registered signal and its access
      effect: read
      questions:
      - Who has access to a particular signal I registered?
      - Can I look up one signal's details by its id?
      instructions:
      - text: Show registered signal {signal_id}.
        slots:
          signal_id: path.signalId
      - text: Get the access records for signal {signal_id}.
        slots:
          signal_id: path.signalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/signals/{signalId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a registered signal
      effect: write
      questions:
      - Can I change a signal's key type or regions after I create it?
      - How do I grant another account access to an existing signal?
      instructions:
      - text: Rename registered signal {signal_id} to {name}.
        slots:
          signal_id: path.signalId
          name: requestBody.name
      - text: Grant access {add_access} on signal {signal_id}.
        slots:
          add_access: requestBody.addAccess
          signal_id: path.signalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/signals/{signalId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Archive a registered signal
      effect: destructive
      questions:
      - What happens to a signal's access records when I delete it?
      - Is deleting a signal permanent or just an archive?
      instructions:
      - text: Delete registered signal {signal_id}.
        slots:
          signal_id: path.signalId
      - text: Archive signal {signal_id} and all its access.
        slots:
          signal_id: path.signalId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/signals/discover'].post
  update:
    x-apievangelist-phrasing:
      intent: Discover available signals from signal agents
      effect: read
      questions:
      - What audience signals are available from signal agents for my targeting?
      - Can I search signal agents for signals matching a description without saving anything?
      instructions:
      - text: Discover signals matching {signal_spec}.
        slots:
          signal_spec: requestBody.signalSpec
      - text: Ask signal agent {agent_id} which signals it offers for {signal_spec}.
        slots:
          agent_id: requestBody.agentId
          signal_spec: requestBody.signalSpec
      method: generated
      generated: '2026-10-01'