# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Iterable Lists API
  version: 1.0.0
extends: openapi/iterable-lists-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: 12
- target: $.paths['/api/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List all lists in the project
      effect: read
      questions:
      - What lists do I have in my /api project, and what's the rate limit?
      - Can I see every static and dynamic list in the project?
      instructions:
      - text: List all lists in my project.
      - text: Show every list from /api/lists.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a static list with a description
      effect: write
      questions:
      - Can I create a static list and give it a description?
      - How do I make a new static list via /api/lists?
      instructions:
      - text: Create a static list named {name}.
        slots:
          name: requestBody.name
      - text: Create static list {name} described as {description}.
        slots:
          name: requestBody.name
          description: requestBody.description
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/lists/getUsers'].get
  update:
    x-apievangelist-phrasing:
      intent: Get all users in a list
      effect: read
      questions:
      - Can I export every member of a list?
      - How slow is pulling all users from a list, given the rate limit?
      instructions:
      - text: Get all users in list {listId}.
        slots:
          listId: query.listId
      - text: Export the members of list {listId}, preferring user IDs {preferUserId}.
        slots:
          listId: query.listId
          preferUserId: query.preferUserId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/lists/previewUsers'].get
  update:
    x-apievangelist-phrasing:
      intent: Preview a random sample of list users
      effect: read
      questions:
      - Can I see a random sample of users in a list rather than all of them?
      - What's the largest sample size for previewing a list?
      instructions:
      - text: Preview users in list {listId}.
        slots:
          listId: query.listId
      - text: Sample {size} random users from list {listId}.
        slots:
          size: query.size
          listId: query.listId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/lists/subscribe'].post
  update:
    x-apievangelist-phrasing:
      intent: Add subscribers to a list
      effect: write
      questions:
      - How do I add specific people to a list under /api/lists?
      - Can I add subscribers only if they already exist as users?
      instructions:
      - text: Add {subscribers} to list {listId}.
        slots:
          subscribers: requestBody.subscribers
          listId: requestBody.listId
      - text: Subscribe {subscribers} to list {listId}, updating existing users only {updateExistingUsersOnly}.
        slots:
          subscribers: requestBody.subscribers
          listId: requestBody.listId
          updateExistingUsersOnly: requestBody.updateExistingUsersOnly
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/lists/unsubscribe'].post
  update:
    x-apievangelist-phrasing:
      intent: Remove users from a list
      effect: write
      questions:
      - Can I remove users from a list and also unsubscribe them from the channel?
      - Is it possible to attribute a list removal to a campaign?
      instructions:
      - text: Remove {subscribers} from list {listId}.
        slots:
          subscribers: requestBody.subscribers
          listId: requestBody.listId
      - text: Remove {subscribers} from list {listId} and unsubscribe them from the channel {channelUnsubscribe}.
        slots:
          subscribers: requestBody.subscribers
          listId: requestBody.listId
          channelUnsubscribe: requestBody.channelUnsubscribe
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/lists/{listId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a list
      effect: destructive
      questions:
      - How do I delete a list I no longer need?
      - Can a list be removed by its ID?
      instructions:
      - text: Delete list {listId}.
        slots:
          listId: path.listId
      - text: Remove list {listId} from the project.
        slots:
          listId: path.listId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/api/lists/{listId}/size'].get
  update:
    x-apievangelist-phrasing:
      intent: Count users in a list
      effect: read
      questions:
      - How many users are on this list?
      - What's the size of a given list?
      instructions:
      - text: Count users in list {listId}.
        slots:
          listId: path.listId
      - text: Tell me the size of list {listId}.
        slots:
          listId: path.listId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/lists'].get
  update:
    x-apievangelist-phrasing:
      intent: List subscriber lists with sizes
      effect: read
      questions:
      - Is there a plain /lists endpoint that returns lists with their size and creation date?
      - Which lists exist and when was each created?
      instructions:
      - text: List subscriber lists from the plain /lists endpoint.
      - text: Show each list's name, size and creation date.
      method: generated
      generated: '2026-10-01'
- target: $.paths['/lists'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a subscriber list (simple)
      effect: write
      questions:
      - Can I create a list with just a name through the basic /lists endpoint?
      - What's the minimum needed to create a subscriber list?
      instructions:
      - text: Create subscriber list {name} via /lists.
        slots:
          name: requestBody.name
      - text: Make a new list called {name} with the simple endpoint.
        slots:
          name: requestBody.name
      method: generated
      generated: '2026-10-01'
- target: $.paths['/lists/subscribe'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe users to a list by email
      effect: write
      questions:
      - Can I add users to a list by email address through the plain /lists path?
      - Which basic endpoint subscribes several emails to a list?
      instructions:
      - text: Using /lists/subscribe, add emails {subscribers} to list {listId}.
        slots:
          subscribers: requestBody.subscribers
          listId: requestBody.listId
      - text: Subscribe {subscribers} to list {listId} with the simple endpoint.
        slots:
          subscribers: requestBody.subscribers
          listId: requestBody.listId
      method: generated
      generated: '2026-10-01'
- target: $.paths['/lists/unsubscribe'].post
  update:
    x-apievangelist-phrasing:
      intent: Unsubscribe users from a list by email
      effect: write
      questions:
      - Can I unsubscribe email addresses from a list via the plain /lists path?
      - Which basic call takes people off a subscriber list?
      instructions:
      - text: Using /lists/unsubscribe, remove {subscribers} from list {listId}.
        slots:
          subscribers: requestBody.subscribers
          listId: requestBody.listId
      - text: Unsubscribe emails {subscribers} from list {listId} with the simple endpoint.
        slots:
          subscribers: requestBody.subscribers
          listId: requestBody.listId
      method: generated
      generated: '2026-10-01'