API Evangelist conversational phrasing for Plunk Contacts API

# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Plunk Contacts API
  version: 1.0.0
extends: openapi/plunk-contacts-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: 10
- target: $.paths['/contacts'].get
  update:
    x-apievangelist-phrasing:
      intent: List contacts
      effect: read
      questions:
      - Which contacts are on my Plunk mailing list?
      - Can I list only the contacts who have unsubscribed?
      - What's the maximum number of contacts I can get back per page?
      instructions:
      - text: List my contacts, 100 per page.
      - text: Show contacts whose email contains {search}.
        slots:
          search: query.search
      - text: List contacts filtered to subscribed = {subscribed}.
        slots:
          subscribed: query.subscribed
      - text: Get the next page of contacts using cursor {cursor}.
        slots:
          cursor: query.cursor
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a contact by id in the request body
      effect: write
      questions:
      - Is there an update endpoint where the contact id goes in the body rather than the URL?
      - Can I set a contact's metadata with the older PUT contacts call?
      instructions:
      - text: Using the body-id PUT endpoint, set contact {id} subscribed to {subscribed}.
        slots:
          id: requestBody.id
          subscribed: requestBody.subscribed
      - text: Via PUT /contacts, replace the metadata of contact {id} with {data}.
        slots:
          id: requestBody.id
          data: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or upsert a contact by email
      effect: write
      questions:
      - How do I add a new contact to my list?
      - If the email already exists, will adding a contact update it instead of duplicating it?
      instructions:
      - text: Add {email} as a contact.
        slots:
          email: requestBody.email
      - text: Upsert contact {email} with subscribed {subscribed} and data {data}.
        slots:
          email: requestBody.email
          subscribed: requestBody.subscribed
          data: requestBody.data
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a contact by id in the request body
      effect: destructive
      questions:
      - Can I delete a contact by sending its id in the request body?
      - Is there a delete call on the bare contacts path without an id in the URL?
      instructions:
      - text: Using the body-id DELETE /contacts call, permanently delete contact {id}.
        slots:
          id: requestBody.id
      - text: Send contact id {id} in the body to erase that contact.
        slots:
          id: requestBody.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a single contact
      effect: read
      questions:
      - How do I look up one contact's details by their id?
      - What data is stored on a particular contact?
      instructions:
      - text: Fetch contact {id}.
        slots:
          id: path.id
      - text: Show me the subscription state and data for contact {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Permanently delete a contact by URL id
      effect: destructive
      questions:
      - How do I permanently remove a contact when I have its id for the URL path?
      - Is deleting a contact reversible?
      instructions:
      - text: Permanently delete contact {id} via its own contact URL.
        slots:
          id: path.id
      - text: Erase the contact whose id is {id} from the URL path.
        slots:
          id: path.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/{id}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Patch a contact's email, subscription or data
      effect: write
      questions:
      - Can I change a contact's email address?
      - What happens if I change a contact's email to one another contact already uses?
      - Can I remove a single data key from a contact by setting it to null?
      instructions:
      - text: Change the email of contact {id} to {email}.
        slots:
          id: path.id
          email: requestBody.email
      - text: Patch contact {id} data with {data}.
        slots:
          id: path.id
          data: requestBody.data
      - text: Patch contact {id} so subscribed is {subscribed}.
        slots:
          id: path.id
          subscribed: requestBody.subscribed
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/count'].get
  update:
    x-apievangelist-phrasing:
      intent: Count all contacts
      effect: read
      questions:
      - How many contacts are in my project in total?
      - What's the size of my whole contact list?
      instructions:
      - text: Count my contacts.
      - text: Tell me the total number of contacts in the project.
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/subscribe'].post
  update:
    x-apievangelist-phrasing:
      intent: Subscribe a contact
      effect: write
      questions:
      - How do I resubscribe someone who previously opted out?
      - Is there a one-step call to mark a contact as subscribed?
      instructions:
      - text: Subscribe contact {id}.
        slots:
          id: requestBody.id
      - text: Opt contact {id} back into emails.
        slots:
          id: requestBody.id
      method: generated
      generated: '2026-09-26'
- target: $.paths['/contacts/unsubscribe'].post
  update:
    x-apievangelist-phrasing:
      intent: Unsubscribe a contact
      effect: write
      questions:
      - How do I unsubscribe a contact who asked to stop getting emails?
      - Can I opt someone out without deleting their contact record?
      instructions:
      - text: Unsubscribe contact {id}.
        slots:
          id: requestBody.id
      - text: Opt contact {id} out of all emails.
        slots:
          id: requestBody.id
      method: generated
      generated: '2026-09-26'