# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Iterable Catalogs API
  version: 1.0.0
extends: openapi/iterable-catalogs-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: 17
- target: $.paths['/api/catalogs'].get
  update:
    x-apievangelist-phrasing:
      intent: List catalog names
      effect: read
      questions:
      - What catalogs exist in my Iterable project?
      - Can I page through catalog names if I have a lot of them?
      instructions:
      - text: List my catalog names.
      - text: Show catalog names, page {page} with {pageSize} per page.
        slots:
          page: query.page
          pageSize: query.pageSize
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a new catalog
      effect: write
      questions:
      - How do I create a catalog for product data?
      - What naming rules apply to a new catalog's name?
      instructions:
      - text: Create a catalog named {catalogName}.
        slots:
          catalogName: path.catalogName
      - text: Set up a new empty catalog called {catalogName}.
        slots:
          catalogName: path.catalogName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a catalog and its collections
      effect: destructive
      questions:
      - Does deleting a catalog also remove the collections that reference it?
      - Can I remove a catalog through the /api/catalogs endpoint?
      instructions:
      - text: Delete catalog {catalogName} and every collection that references it.
        slots:
          catalogName: path.catalogName
      - text: Remove catalog {catalogName} via /api/catalogs.
        slots:
          catalogName: path.catalogName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}/fieldMappings'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a catalog's field data types
      effect: read
      questions:
      - Which data types are mapped to the fields in my catalog?
      - Can I find catalog fields that don't have a type defined yet?
      instructions:
      - text: Show the field mappings for catalog {catalogName}.
        slots:
          catalogName: path.catalogName
      - text: List undefined fields in catalog {catalogName}.
        slots:
          catalogName: path.catalogName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}/fieldMappings'].put
  update:
    x-apievangelist-phrasing:
      intent: Set data types for catalog fields
      effect: write
      questions:
      - Can I change a catalog field's data type after it has been set?
      - Which types can I assign to catalog fields, like date or geo_location?
      instructions:
      - text: Set field mappings {mappingsUpdates} on catalog {catalogName}.
        slots:
          mappingsUpdates: requestBody.mappingsUpdates
          catalogName: path.catalogName
      - text: Define data types for catalog {catalogName} fields as {mappingsUpdates}.
        slots:
          catalogName: path.catalogName
          mappingsUpdates: requestBody.mappingsUpdates
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List catalog items with sorting
      effect: read
      questions:
      - Can I sort the items in a catalog by a field, ascending or descending?
      - What's the rate limit on listing catalog items under /api/catalogs?
      instructions:
      - text: List items in catalog {catalogName} ordered by {orderBy}.
        slots:
          catalogName: path.catalogName
          orderBy: query.orderBy
      - text: Show catalog {catalogName} items page {page}, sorted ascending {sortAscending}.
        slots:
          catalogName: path.catalogName
          page: query.page
          sortAscending: query.sortAscending
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}/items'].post
  update:
    x-apievangelist-phrasing:
      intent: Bulk create catalog items
      effect: write
      questions:
      - How many catalog items can I create in one request?
      - Can I bulk upload items and replace only the fields I send?
      instructions:
      - text: Bulk create items {documents} in catalog {catalogName}.
        slots:
          documents: requestBody.documents
          catalogName: path.catalogName
      - text: Upload items {documents} to catalog {catalogName} with replace-uploaded-fields-only set to {replaceUploadedFieldsOnly}.
        slots:
          documents: requestBody.documents
          catalogName: path.catalogName
          replaceUploadedFieldsOnly: requestBody.replaceUploadedFieldsOnly
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}/items'].delete
  update:
    x-apievangelist-phrasing:
      intent: Bulk delete catalog items
      effect: destructive
      questions:
      - Can I delete many catalog items at once by their IDs?
      - Is bulk deletion of catalog items processed asynchronously?
      instructions:
      - text: Delete items {itemIds} from catalog {catalogName}.
        slots:
          itemIds: requestBody.itemIds
          catalogName: path.catalogName
      - text: Bulk remove catalog {catalogName} items {itemIds}.
        slots:
          catalogName: path.catalogName
          itemIds: requestBody.itemIds
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}/items/{itemId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single catalog item
      effect: read
      questions:
      - How do I look up one product in a catalog by its item ID?
      - What fields does a single catalog item return?
      instructions:
      - text: Get item {itemId} from catalog {catalogName}.
        slots:
          itemId: path.itemId
          catalogName: path.catalogName
      - text: Show catalog {catalogName} item {itemId}.
        slots:
          catalogName: path.catalogName
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}/items/{itemId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a catalog item
      effect: write
      questions:
      - Can I fully overwrite a catalog item rather than merging fields under /api/catalogs?
      - What characters are allowed in a catalog item ID when replacing it?
      instructions:
      - text: Replace item {itemId} in catalog {catalogName} with {value}.
        slots:
          itemId: path.itemId
          catalogName: path.catalogName
          value: requestBody.value
      - text: Overwrite /api catalog {catalogName} item {itemId} entirely using {value}.
        slots:
          catalogName: path.catalogName
          itemId: path.itemId
          value: requestBody.value
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}/items/{itemId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete one catalog item asynchronously
      effect: destructive
      questions:
      - Is a deleted catalog item removed immediately or eventually?
      - Can I delete a single item through the /api/catalogs items path?
      instructions:
      - text: Delete item {itemId} from catalog {catalogName} via /api/catalogs.
        slots:
          itemId: path.itemId
          catalogName: path.catalogName
      - text: Asynchronously remove item {itemId} in catalog {catalogName}.
        slots:
          itemId: path.itemId
          catalogName: path.catalogName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/catalogs/{catalogName}/items/{itemId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Create or partially update a catalog item
      effect: write
      questions:
      - Can I update just a few fields of a catalog item without replacing it?
      - Will a partial update create the catalog item if it doesn't exist?
      instructions:
      - text: Update fields {update} on item {itemId} in catalog {catalogName}.
        slots:
          update: requestBody.update
          itemId: path.itemId
          catalogName: path.catalogName
      - text: Merge {update} into catalog {catalogName} item {itemId}, creating it if missing.
        slots:
          update: requestBody.update
          catalogName: path.catalogName
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/catalogs/{catalogName}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a catalog's definition
      effect: read
      questions:
      - Can I fetch a catalog by name with its field definitions and metadata?
      - What metadata is stored on a catalog itself?
      instructions:
      - text: Get catalog {catalogName} with its field definitions.
        slots:
          catalogName: path.catalogName
      - text: Show the metadata for catalog {catalogName}.
        slots:
          catalogName: path.catalogName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/catalogs/{catalogName}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a catalog and all its items
      effect: destructive
      questions:
      - Does deleting a catalog through the plain /catalogs path remove all of its items?
      - What gets wiped when I delete a catalog using the simple endpoint?
      instructions:
      - text: Delete catalog {catalogName} and all its items using /catalogs.
        slots:
          catalogName: path.catalogName
      - text: Wipe catalog {catalogName} with the simple delete endpoint.
        slots:
          catalogName: path.catalogName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/catalogs/{catalogName}/items'].get
  update:
    x-apievangelist-phrasing:
      intent: List catalog items via the simple endpoint
      effect: read
      questions:
      - Can I page through catalog items with the plain /catalogs path?
      - Which basic endpoint just lists catalog items without sorting options?
      instructions:
      - text: List items in catalog {catalogName} via /catalogs.
        slots:
          catalogName: path.catalogName
      - text: Page {page} of catalog {catalogName} items from the simple endpoint.
        slots:
          page: query.page
          catalogName: path.catalogName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/catalogs/{catalogName}/items/{itemId}'].put
  update:
    x-apievangelist-phrasing:
      intent: Create or replace a catalog item (simple)
      effect: write
      questions:
      - Is there a plain /catalogs endpoint to create or replace an item by ID?
      - Can I upsert a whole catalog item with field values via the basic path?
      instructions:
      - text: Using /catalogs, create or replace item {itemId} in catalog {catalogName} with {value}.
        slots:
          itemId: path.itemId
          catalogName: path.catalogName
          value: requestBody.value
      - text: Put item {itemId} into catalog {catalogName} via the simple endpoint.
        slots:
          itemId: path.itemId
          catalogName: path.catalogName
      method: generated
      generated: '2026-10-01'
- target: $.paths['/catalogs/{catalogName}/items/{itemId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a catalog item (simple)
      effect: destructive
      questions:
      - Can I delete a catalog item by ID through the plain /catalogs path?
      - Which basic endpoint removes one item from a catalog?
      instructions:
      - text: Delete item {itemId} from catalog {catalogName} using /catalogs.
        slots:
          itemId: path.itemId
          catalogName: path.catalogName
      - text: Remove catalog {catalogName} item {itemId} with the simple endpoint.
        slots:
          catalogName: path.catalogName
          itemId: path.itemId
      method: generated
      generated: '2026-10-01'