# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kit Subscribers API
  version: 1.0.0
extends: openapi/convertkit-subscribers-api-openapi.yml
actions:
- target: $.info
  update:
    x-apievangelist-phrasing:
      method: generated
      generated: '2026-10-02'
      generator: build-phrasing.py
      label: Generated by API Evangelist
      operations: 9
- target: $.paths['/v4/bulk/subscribers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create many subscribers at once
      effect: write
      questions:
      - Can I import thousands of subscribers in one request?
      - How do I get told when a bulk subscriber import finishes processing?
      instructions:
      - text: 'Bulk create these subscribers: {subscribers}.'
        slots:
          subscribers: requestBody.subscribers
      - text: Import {subscribers} in bulk and post the result to {callback_url}.
        slots:
          subscribers: requestBody.subscribers
          callback_url: requestBody.callback_url
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/subscribers'].get
  update:
    x-apievangelist-phrasing:
      intent: List and filter subscribers
      effect: read
      questions:
      - Which subscribers joined my list in the last month?
      - Can I find a subscriber by email address in the subscriber list?
      - Is it possible to list only bounced or cancelled subscribers?
      instructions:
      - text: List subscribers created after {created_after}.
        slots:
          created_after: query.created_after
      - text: Find the subscriber with email {email_address}.
        slots:
          email_address: query.email_address
      - text: List subscribers with status {status}.
        slots:
          status: query.status
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/subscribers'].post
  update:
    x-apievangelist-phrasing:
      intent: Create or upsert a subscriber
      effect: write
      questions:
      - How do I add a new subscriber to my email list?
      - What happens if I create a subscriber whose email already exists?
      instructions:
      - text: Create a subscriber with email {email_address} and first name {first_name}.
        slots:
          email_address: requestBody.email_address
          first_name: requestBody.first_name
      - text: Add {email_address} as a new subscriber in state {state}.
        slots:
          email_address: requestBody.email_address
          state: requestBody.state
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/subscribers/filter'].post
  update:
    x-apievangelist-phrasing:
      intent: Filter subscribers by engagement
      effect: read
      questions:
      - Which subscribers opened or clicked my emails recently?
      - Can I find subscribers who meet several engagement conditions at once?
      instructions:
      - text: 'Find subscribers matching all of these engagement conditions: {all}.'
        slots:
          all: requestBody.all
      - text: Filter subscribers by engagement using {all} with counting mode {counting_mode}.
        slots:
          all: requestBody.all
          counting_mode: requestBody.counting_mode
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/subscribers/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a subscriber
      effect: read
      questions:
      - Can I look up one subscriber's details by their id?
      - What state and custom fields does a specific subscriber have?
      instructions:
      - text: Get subscriber {id}.
        slots:
          id: path.id
      - text: Show me the profile and custom fields of subscriber {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/subscribers/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update a subscriber's details
      effect: write
      questions:
      - How do I change an existing subscriber's email address or first name?
      - Why does updating a subscriber fail when I pass an unknown custom field key?
      instructions:
      - text: Change subscriber {id}'s email to {email_address}.
        slots:
          id: path.id
          email_address: requestBody.email_address
      - text: Update subscriber {id} with email {email_address} and custom fields {fields}.
        slots:
          id: path.id
          email_address: requestBody.email_address
          fields: requestBody.fields
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/subscribers/{id}/unsubscribe'].post
  update:
    x-apievangelist-phrasing:
      intent: Unsubscribe a subscriber
      effect: destructive
      questions:
      - How do I unsubscribe someone from all my emails?
      - Can I cancel a subscriber's subscription through the API?
      instructions:
      - text: Unsubscribe subscriber {id}.
        slots:
          id: path.id
      - text: Stop all emails to subscriber {id} by unsubscribing them.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/subscribers/{subscriber_id}/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get email stats for one subscriber
      effect: read
      questions:
      - How engaged is a specific subscriber with my emails?
      - Can I limit a subscriber's open and click stats to emails sent in a date range?
      instructions:
      - text: Show email stats for subscriber {subscriber_id}.
        slots:
          subscriber_id: path.subscriber_id
      - text: Get subscriber {subscriber_id}'s stats for emails sent after {email_sent_after}.
        slots:
          subscriber_id: path.subscriber_id
          email_sent_after: query.email_sent_after
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/subscribers/{subscriber_id}/tags'].get
  update:
    x-apievangelist-phrasing:
      intent: List a subscriber's tags
      effect: read
      questions:
      - Which tags are applied to a particular subscriber?
      - Can I see every tag one person has been given?
      instructions:
      - text: List the tags on subscriber {subscriber_id}.
        slots:
          subscriber_id: path.subscriber_id
      - text: Show which tags subscriber {subscriber_id} has.
        slots:
          subscriber_id: path.subscriber_id
      method: generated
      generated: '2026-10-02'