# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Mirakl Platform Settings API
  version: 1.0.0
extends: openapi/mirakl-platform-settings-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: 20
- target: $.paths['/api/additional_fields'].get
  update:
    x-apievangelist-phrasing:
      intent: List the platform's custom fields
      effect: read
      questions:
      - Which custom fields has the operator defined on the marketplace?
      - Can I see only the custom fields that apply to offers or to shops?
      instructions:
      - text: List all custom fields configured on the platform.
      - text: Show the custom fields defined for {entities}.
        slots:
          entities: query.entities
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/channels'].get
  update:
    x-apievangelist-phrasing:
      intent: List enabled sales channels
      effect: read
      questions:
      - Which sales channels are enabled on my Mirakl marketplace?
      - What channel codes can I use when pricing offers per channel?
      instructions:
      - text: List every enabled channel sorted by code.
      - text: Show the channels enabled for shop {shop_id}.
        slots:
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/currencies'].get
  update:
    x-apievangelist-phrasing:
      intent: List activated currencies
      effect: read
      questions:
      - Which currencies are activated on the marketplace platform?
      - What are the currency codes and labels I can use for prices?
      instructions:
      - text: List the currency codes and labels active on the platform.
      - text: Show the currencies available to shop {shop_id}.
        slots:
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/documents'].get
  update:
    x-apievangelist-phrasing:
      intent: List document types
      effect: read
      questions:
      - What kinds of documents can be attached to orders or shops on the marketplace?
      - Which document types are defined for a given entity?
      instructions:
      - text: List all document types configured on the platform.
      - text: Show the document types available for {entities}.
        slots:
          entities: query.entities
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/locales'].get
  update:
    x-apievangelist-phrasing:
      intent: List platform locales
      effect: read
      questions:
      - Which locales and languages does the marketplace support?
      - What locale codes should my PIM use when exporting product formats?
      instructions:
      - text: List the locale codes and labels of the platform.
      - text: Show the locales available to shop {shop_id}.
        slots:
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/platform/configuration'].get
  update:
    x-apievangelist-phrasing:
      intent: Get platform modules and features
      effect: read
      questions:
      - Which modules and major features were activated when the platform was set up?
      - Is a given feature enabled on our marketplace platform configuration?
      instructions:
      - text: Show the platform configuration with its activated modules and features.
      - text: Get the general platform information and feature flags as seen by shop {shop_id}.
        slots:
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/version'].get
  update:
    x-apievangelist-phrasing:
      intent: Check the platform is up
      effect: read
      questions:
      - Is the Mirakl platform up right now?
      - What endpoint can I ping as a health check before running my sync jobs?
      instructions:
      - text: Run a health check against the marketplace platform.
      - text: Check whether the platform responds for shop {shop_id}.
        slots:
          shop_id: query.shop_id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/offers/states'].get
  update:
    x-apievangelist-phrasing:
      intent: List offer conditions
      effect: read
      questions:
      - What offer conditions like new or refurbished can sellers choose from?
      - Can I list only the active offer states?
      instructions:
      - text: List all offer conditions in back-office order.
      - text: Show offer conditions filtered by active status {active}.
        slots:
          active: query.active
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/reasons'].get
  update:
    x-apievangelist-phrasing:
      intent: List all reason types at once
      effect: read
      questions:
      - Where do I get every cancellation, refund, incident and message reason in one call?
      - What reasons can a customer or seller pick when refunding or cancelling?
      instructions:
      - text: List all reasons of every type sorted by type then index.
      - text: Fetch the full set of cancellation, refund, incident and messaging reasons.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/reasons/{reason_type}'].get
  update:
    x-apievangelist-phrasing:
      intent: List reasons of a single type (deprecated)
      effect: read
      questions:
      - Can I fetch only the reasons for one reason type using the older per-type endpoint?
      - Is the list-reasons-by-type endpoint still supported or being removed?
      instructions:
      - text: List the reasons of type {reason_type} using the deprecated per-type endpoint.
        slots:
          reason_type: path.reason_type
      - text: Get only {reason_type} reasons sorted by index.
        slots:
          reason_type: path.reason_type
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/reasons/incident_open'].get
  update:
    x-apievangelist-phrasing:
      intent: List incident-opening reasons (deprecated)
      effect: read
      questions:
      - What reasons can be used to open an incident on an order line?
      - Which incident open reasons is my role allowed to use?
      instructions:
      - text: List the reasons for opening an incident.
      - text: Show incident-open reasons from the legacy dedicated endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/reasons/incident_close'].get
  update:
    x-apievangelist-phrasing:
      intent: List incident-closing reasons (deprecated)
      effect: read
      questions:
      - What reasons can be given when closing an incident?
      - Which incident close reasons does my role have access to?
      instructions:
      - text: List the reasons for closing an incident.
      - text: Show incident-close reasons from the legacy dedicated endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/reasons/messaging'].get
  update:
    x-apievangelist-phrasing:
      intent: List messaging reasons (deprecated)
      effect: read
      questions:
      - What subjects or reasons can be chosen when sending a message?
      - Which messaging reasons are available to my user role?
      instructions:
      - text: List the messaging reasons.
      - text: Show message reasons from the legacy messaging-reasons endpoint.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/shipping/zones'].get
  update:
    x-apievangelist-phrasing:
      intent: List active shipping zones
      effect: read
      questions:
      - Which shipping zones are active on the marketplace?
      - What zone codes can I use when filtering offers by shipping destination?
      instructions:
      - text: List all active shipping zones.
      - text: Show the shipping zones in back-office order.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/shipping/types'].get
  update:
    x-apievangelist-phrasing:
      intent: List active shipping methods
      effect: read
      questions:
      - What shipping methods like standard or express are active?
      - Which shipping type codes can sellers configure for delivery?
      instructions:
      - text: List all active shipping methods.
      - text: Show the shipping types available on the platform.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/shipping/carriers'].get
  update:
    x-apievangelist-phrasing:
      intent: List carriers on the platform
      effect: read
      questions:
      - Which carriers can sellers pick when adding tracking to a shipment?
      - What carrier codes are configured on the marketplace?
      instructions:
      - text: List all carriers sorted alphabetically by label.
      - text: Show every carrier code and label the platform knows.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/shipping/logistic_classes'].get
  update:
    x-apievangelist-phrasing:
      intent: List logistic classes
      effect: read
      questions:
      - What logistic classes are defined for pricing shipping by parcel size?
      - Which logistic class codes can I assign to an offer?
      instructions:
      - text: List all logistic classes.
      - text: Show the logistic classes in back-office order.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/shipping/configuration/shop'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shop's shipping configuration
      effect: read
      questions:
      - What shipping settings are configured for my shop?
      - Can I see a seller's shipping configuration before editing their shipping fees?
      instructions:
      - text: Get the shipping configuration of shop {shop_id}.
        slots:
          shop_id: query.shop_id
      - text: Show my shop's shipping configuration.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/shipping/charges/shop'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a shop's shipping charges
      effect: read
      questions:
      - What shipping fees are configured for my shop account?
      - Can I see only the shipping charges a shop has overridden?
      instructions:
      - text: Get the shipping charges configured for shop {shop_id}.
        slots:
          shop_id: query.shop_id
      - text: Show shipping charges where overridden by shop is {overridden_by_shop}.
        slots:
          overridden_by_shop: query.overridden_by_shop
      method: generated
      generated: '2026-09-26'
- target: $.paths['/api/platform-settings/operator-return-configurations'].get
  update:
    x-apievangelist-phrasing:
      intent: Get operator return configurations
      effect: read
      questions:
      - What return policies has the operator set up for shops?
      - Where can I read the return configuration the marketplace applies to sellers?
      instructions:
      - text: Get the operator's return configurations for shops.
      - text: Show the return settings configured by the operator.
      method: generated
      generated: '2026-09-26'