# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Admin API V1 Global Synonyms API
  version: 1.0.0
extends: openapi/optimizely-global-synonyms-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-09-26'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/api/v1/admin/GlobalSynonyms'].get
  update:
    x-apievangelist-phrasing:
      intent: List search synonyms
      effect: read
      questions:
      - How do I see all the global search synonyms configured in Optimizely Configured Commerce?
      - Can I filter synonyms by language or synonym type?
      instructions:
      - text: List all global search synonyms.
      - text: List global synonyms matching {filter}.
        slots:
          filter: query.$filter
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GlobalSynonyms'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a search synonym
      effect: write
      questions:
      - How can I make searches for one word also match another term?
      - Can I add a synonym for a specific language?
      instructions:
      - text: Create a {synonymType} synonym mapping {lookupValue} to {mappedValue}.
        slots:
          synonymType: requestBody.synonymType
          lookupValue: requestBody.lookupValue
          mappedValue: requestBody.mappedValue
      - text: Add synonym {lookupValue} -> {mappedValue} in language {languageId}, described as {description}.
        slots:
          lookupValue: requestBody.lookupValue
          mappedValue: requestBody.mappedValue
          languageId: requestBody.languageId
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GlobalSynonyms({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one search synonym
      effect: read
      questions:
      - What does a particular synonym map its lookup term to?
      - Can I select only some fields of one synonym record?
      instructions:
      - text: Show global synonym {id}.
        slots:
          id: path.id
      - text: Get global synonym {id} returning {select}.
        slots:
          id: path.id
          select: query.$select
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GlobalSynonyms({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a search synonym
      effect: write
      questions:
      - Can I overwrite a synonym with a new lookup and mapped value?
      - What's needed to replace an entire synonym record?
      instructions:
      - text: Replace synonym {id} so {lookupValue} maps to {mappedValue}.
        slots:
          id: path.id
          lookupValue: requestBody.lookupValue
          mappedValue: requestBody.mappedValue
      - text: Overwrite synonym record {id} entirely with type {synonymType}.
        slots:
          id: path.id
          synonymType: requestBody.synonymType
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GlobalSynonyms({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a search synonym
      effect: destructive
      questions:
      - How do I stop a synonym from affecting search by deleting it?
      - Can I delete a synonym conditionally on its ETag?
      instructions:
      - text: Delete global synonym {id}.
        slots:
          id: path.id
      - text: Delete synonym {id} if its ETag is {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GlobalSynonyms({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update a search synonym
      effect: write
      questions:
      - Can I change only the mapped term of an existing synonym?
      - How do I edit a synonym's description without touching the rest?
      instructions:
      - text: Patch synonym {id} to map to {mappedValue}.
        slots:
          id: path.id
          mappedValue: requestBody.mappedValue
      - text: Update synonym {id} description to {description}.
        slots:
          id: path.id
          description: requestBody.description
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/GlobalSynonyms/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Get default values for a synonym
      effect: read
      questions:
      - What defaults are pre-filled for a new global synonym?
      - Is there a blank synonym template?
      instructions:
      - text: Get the default global synonym template.
      - text: Show pre-filled values for a new search synonym.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/globalsynonyms/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete several search synonyms
      effect: destructive
      questions:
      - Can I bulk delete a list of synonyms?
      - How do I clear out many search synonyms in one call?
      instructions:
      - text: Bulk delete global synonyms {ids}.
        slots:
          ids: query.ids
      - text: Remove every synonym listed in {ids}.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/globalsynonyms({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property on a synonym
      effect: read
      questions:
      - Can I read a custom property attached to a search synonym?
      - Where are custom attributes on a synonym stored?
      instructions:
      - text: Get custom property {custompropertyKey} on global synonym {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show synonym {key}'s custom property {custompropertyKey}.
        slots:
          key: path.key
          custompropertyKey: path.custompropertyKey
      method: generated
      generated: '2026-09-26'