# 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 Countries API
  version: 1.0.0
extends: openapi/optimizely-countries-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: 11
- target: $.paths['/api/v1/admin/Countries'].get
  update:
    x-apievangelist-phrasing:
      intent: List the countries configured in the store
      effect: read
      questions:
      - Which countries are set up in our Optimizely Commerce admin?
      - Can I filter the country list to only the active ones and sort it by name?
      - Is there a way to get a count of configured countries along with the results?
      instructions:
      - text: List all configured countries.
      - text: List countries matching the filter {filter}, ordered by {orderby}.
        slots:
          filter: query.$filter
          orderby: query.$orderby
      - text: Show the first {top} countries with their states expanded as {expand}.
        slots:
          top: query.$top
          expand: query.$expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Countries'].post
  update:
    x-apievangelist-phrasing:
      intent: Add a new country
      effect: write
      questions:
      - What ISO codes and unit settings are required to add a country?
      - Can I block anonymous traffic from a country when I add it?
      instructions:
      - text: Add the country {name} with abbreviation {abbreviation}, ISO codes {isoCode2} and {isoCode3}, ISO number {isoNumber}, using {distanceUnitOfMeasure}.
        slots:
          name: requestBody.name
          abbreviation: requestBody.abbreviation
          isoCode2: requestBody.isoCode2
          isoCode3: requestBody.isoCode3
          isoNumber: requestBody.isoNumber
          distanceUnitOfMeasure: requestBody.distanceUnitOfMeasure
      - text: Create country {name} ({isoCode2}/{isoCode3}, number {isoNumber}, abbreviation {abbreviation}, distance unit {distanceUnitOfMeasure}) as inactive.
        slots:
          name: requestBody.name
          isoCode2: requestBody.isoCode2
          isoCode3: requestBody.isoCode3
          isoNumber: requestBody.isoNumber
          abbreviation: requestBody.abbreviation
          distanceUnitOfMeasure: requestBody.distanceUnitOfMeasure
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Countries({id})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a country by id
      effect: read
      questions:
      - How do I look up one country's ISO codes and VAT default by its id?
      - Can I select only certain fields when fetching a single country?
      instructions:
      - text: Get country {id}.
        slots:
          id: path.id
      - text: Show only the fields {select} for country {id}.
        slots:
          select: query.$select
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Countries({id})'].put
  update:
    x-apievangelist-phrasing:
      intent: Replace a country record
      effect: write
      questions:
      - Can I overwrite a country's whole record, including its ISO codes, in one call?
      - Does a full replace of a country reset fields I leave out?
      instructions:
      - text: Replace country {id} with name {name}, abbreviation {abbreviation}, codes {isoCode2}/{isoCode3}, number {isoNumber}, unit {distanceUnitOfMeasure}.
        slots:
          id: path.id
          name: requestBody.name
          abbreviation: requestBody.abbreviation
          isoCode2: requestBody.isoCode2
          isoCode3: requestBody.isoCode3
          isoNumber: requestBody.isoNumber
          distanceUnitOfMeasure: requestBody.distanceUnitOfMeasure
      - text: Overwrite the full record of country {id} with a new definition.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Countries({id})'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a country
      effect: destructive
      questions:
      - Can I remove a single country from the store configuration?
      - Does deleting a country support an If-Match concurrency check?
      instructions:
      - text: Delete country {id}.
        slots:
          id: path.id
      - text: Delete country {id} only if its ETag still matches {etag}.
        slots:
          id: path.id
          etag: header.If-Match
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Countries({id})'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update fields on a country
      effect: write
      questions:
      - How do I deactivate a country without resending all its details?
      - Can I change a country's default VAT code with a partial update?
      instructions:
      - text: Set isActive to {isActive} on country {id}.
        slots:
          isActive: requestBody.isActive
          id: path.id
      - text: Patch country {id} so its default VAT code is {defaultVatCodeId}.
        slots:
          id: path.id
          defaultVatCodeId: requestBody.defaultVatCodeId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/Countries/Default.Default()'].get
  update:
    x-apievangelist-phrasing:
      intent: Call the countries Default function
      effect: read
      questions:
      - What does the Default function on the Countries set return?
      - Is there an endpoint that gives me the default country entry?
      instructions:
      - text: Call the Default function on countries.
      - text: Fetch the default country result.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/countries/delete'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete countries by id
      effect: destructive
      questions:
      - Can I delete several countries in one request by passing a list of ids?
      - Is there a bulk removal route for countries?
      instructions:
      - text: Delete the countries with ids {ids}.
        slots:
          ids: query.ids
      - text: Bulk remove countries {ids} in one call.
        slots:
          ids: query.ids
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/countries({key})/customproperties({custompropertyKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a custom property of a country
      effect: read
      questions:
      - Where do I read a custom property value stored on a country?
      - Can I fetch one named custom property for a given country?
      instructions:
      - text: Get custom property {custompropertyKey} of country {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      - text: Show the value of custom property {custompropertyKey} on country {key}.
        slots:
          custompropertyKey: path.custompropertyKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/countries({key})/states({stateKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a state within a country
      effect: read
      questions:
      - How do I look up a specific state or province that belongs to a country?
      - Can I fetch one state record through its parent country?
      instructions:
      - text: Get state {stateKey} of country {key}.
        slots:
          stateKey: path.stateKey
          key: path.key
      - text: Show the province {stateKey} under country {key}.
        slots:
          stateKey: path.stateKey
          key: path.key
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/v1/admin/countries({key})/websites({websiteKey})'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a website linked to a country
      effect: read
      questions:
      - Which storefront websites is a country assigned to?
      - Can I check whether a particular website is linked to a country?
      instructions:
      - text: Get website {websiteKey} linked to country {key}.
        slots:
          websiteKey: path.websiteKey
          key: path.key
      - text: Check the website {websiteKey} assignment for country {key}.
        slots:
          websiteKey: path.websiteKey
          key: path.key
      method: generated
      generated: '2026-09-26'