# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Kit Broadcasts API
  version: 1.0.0
extends: openapi/convertkit-broadcasts-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: 8
- target: $.paths['/v4/broadcasts'].get
  update:
    x-apievangelist-phrasing:
      intent: List broadcasts
      effect: read
      questions:
      - Which broadcasts have I sent or drafted in my newsletter account?
      - Can I list only the broadcasts sent within a certain date range?
      - What's the maximum number of broadcasts returned per page?
      instructions:
      - text: List my broadcasts sent after {sent_after}.
        slots:
          sent_after: query.sent_after
      - text: Show broadcasts sent between {sent_after} and {sent_before}.
        slots:
          sent_after: query.sent_after
          sent_before: query.sent_before
      - text: List all my broadcasts, {per_page} per page.
        slots:
          per_page: query.per_page
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/broadcasts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create, draft or schedule a broadcast
      effect: write
      questions:
      - How do I schedule a new email broadcast to go out at a specific time?
      - Can I save a new broadcast as a draft instead of sending it right away?
      - Is it possible to send a new broadcast to only a filtered subset of subscribers?
      instructions:
      - text: Create a new broadcast with subject {subject} and schedule it for {send_at}.
        slots:
          subject: requestBody.subject
          send_at: requestBody.send_at
      - text: 'Draft a new broadcast titled {subject} using this HTML: {content}.'
        slots:
          subject: requestBody.subject
          content: requestBody.content
      - text: Start a new broadcast {subject} that only goes to subscribers matching {subscriber_filter}.
        slots:
          subject: requestBody.subject
          subscriber_filter: requestBody.subscriber_filter
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/broadcasts/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stats across many broadcasts
      effect: read
      questions:
      - How did all my recent broadcasts perform side by side?
      - Can I pull open and click stats for every broadcast sent in a date range at once?
      instructions:
      - text: Get stats for all broadcasts sent after {sent_after}.
        slots:
          sent_after: query.sent_after
      - text: Compare performance stats for every broadcast sent before {sent_before}.
        slots:
          sent_before: query.sent_before
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/broadcasts/{broadcast_id}/clicks'].get
  update:
    x-apievangelist-phrasing:
      intent: Get link clicks for one broadcast
      effect: read
      questions:
      - Which links in a broadcast got the most clicks?
      - Can I see the per-link click breakdown for a single email I sent?
      instructions:
      - text: Show the link clicks for broadcast {broadcast_id}.
        slots:
          broadcast_id: path.broadcast_id
      - text: Break down which URLs subscribers clicked in broadcast {broadcast_id}.
        slots:
          broadcast_id: path.broadcast_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/broadcasts/{broadcast_id}/stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get stats for one broadcast
      effect: read
      questions:
      - What was the open rate and click rate for a specific broadcast?
      - How many unsubscribes did one particular broadcast cause?
      instructions:
      - text: Show me the performance stats for broadcast {broadcast_id}.
        slots:
          broadcast_id: path.broadcast_id
      - text: Report recipients, opens and clicks for broadcast {broadcast_id}.
        slots:
          broadcast_id: path.broadcast_id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/broadcasts/{id}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get a broadcast's details
      effect: read
      questions:
      - Can I fetch the subject, content and schedule of one existing broadcast?
      - What settings does a particular broadcast have saved right now?
      instructions:
      - text: Get the details of broadcast {id}.
        slots:
          id: path.id
      - text: Show me the subject line and send time saved on broadcast {id}.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/broadcasts/{id}'].put
  update:
    x-apievangelist-phrasing:
      intent: Update an existing broadcast
      effect: write
      questions:
      - How do I change the subject or content of a broadcast I already drafted?
      - Can I reschedule an existing broadcast to a different send time?
      instructions:
      - text: Change the subject of existing broadcast {id} to {subject}.
        slots:
          id: path.id
          subject: requestBody.subject
      - text: Reschedule broadcast {id} to send at {send_at}.
        slots:
          id: path.id
          send_at: requestBody.send_at
      - text: Replace the HTML body of drafted broadcast {id} with {content}.
        slots:
          id: path.id
          content: requestBody.content
      method: generated
      generated: '2026-10-02'
- target: $.paths['/v4/broadcasts/{id}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete a broadcast
      effect: destructive
      questions:
      - How do I get rid of a broadcast draft I no longer need?
      - Can a scheduled broadcast be deleted through the API?
      instructions:
      - text: Delete broadcast {id}.
        slots:
          id: path.id
      - text: Remove the broadcast {id} from my account permanently.
        slots:
          id: path.id
      method: generated
      generated: '2026-10-02'