# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kit Forms API
  version: 1.0.0
extends: openapi/convertkit-forms-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: 5
- target: $.paths['/v4/bulk/forms/subscribers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add many subscribers to forms at once
      effect: write
      questions:
      - Can I add a large batch of subscribers to forms in one request?
      - Will bulk-adding people to a double opt-in form send them the incentive email?
      instructions:
      - text: 'Bulk add these subscribers to forms: {additions}.'
        slots:
          additions: requestBody.additions
      - text: Add the subscriber-form pairs {additions} in bulk and notify {callback_url} when finished.
        slots:
          additions: requestBody.additions
          callback_url: requestBody.callback_url
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/forms'].get
  update:
    x-apievangelist-phrasing:
      intent: List forms and landing pages
      effect: read
      questions:
      - What signup forms and landing pages do I have?
      - Can I list only archived or trashed forms?
      - How do I tell embedded forms apart from hosted landing pages?
      instructions:
      - text: List my forms with status {status}.
        slots:
          status: query.status
      - text: Show only my forms of type {type}.
        slots:
          type: query.type
      - text: List all my active signup forms.
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/forms/{form_id}/subscribers'].get
  update:
    x-apievangelist-phrasing:
      intent: List subscribers who joined via a form
      effect: read
      questions:
      - Who signed up through a particular form?
      - Can I see subscribers added to a form after a certain date?
      - Which form signups have since bounced or unsubscribed?
      instructions:
      - text: List subscribers on form {form_id}.
        slots:
          form_id: path.form_id
      - text: Show subscribers added to form {form_id} after {added_after}.
        slots:
          form_id: path.form_id
          added_after: query.added_after
      - text: List form {form_id} subscribers with status {status}.
        slots:
          form_id: path.form_id
          status: query.status
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/forms/{form_id}/subscribers'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an existing subscriber to a form by email
      effect: write
      questions:
      - How do I add someone to a form using just their email address?
      - Does the subscriber need to exist before I add their email to a form?
      instructions:
      - text: Add the subscriber with email {email_address} to form {form_id}.
        slots:
          email_address: requestBody.email_address
          form_id: path.form_id
      - text: Subscribe {email_address} to form {form_id} with referrer {referrer}.
        slots:
          email_address: requestBody.email_address
          form_id: path.form_id
          referrer: requestBody.referrer
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/forms/{form_id}/subscribers/{id}'].post
  update:
    x-apievangelist-phrasing:
      intent: Add an existing subscriber to a form by id
      effect: write
      questions:
      - Can I add a subscriber to a form when I only have their subscriber id?
      - Is there a way to record the referrer when adding a known subscriber id to a form?
      instructions:
      - text: Add subscriber id {id} to form {form_id} with referrer {referrer}.
        slots:
          id: path.id
          form_id: path.form_id
          referrer: requestBody.referrer
      - text: Put subscriber {id} on form {form_id}, crediting referrer {referrer}.
        slots:
          id: path.id
          form_id: path.form_id
          referrer: requestBody.referrer
      method: generated
      generated: '2026-10-02'