# Generated by API Evangelist (build-phrasing.py). Our phrasing, not observed demand.
overlay: 1.0.0
info:
  title: API Evangelist conversational phrasing for Reference Posts API
  version: 1.0.0
extends: openapi/beehiiv-posts-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: 8
- target: $.paths['/publications/{publicationId}/posts'].get
  update:
    x-apievangelist-phrasing:
      intent: List a publication's posts
      effect: read
      questions:
      - What posts have I published on my newsletter?
      - Can I filter posts by content tag or author?
      - Which of my posts are still drafts or scheduled?
      instructions:
      - text: List posts on publication {publication}.
        slots:
          publication: path.publicationId
      - text: Show {status} posts on {publication}.
        slots:
          status: query.status
          publication: path.publicationId
      - text: List posts tagged {content_tags} on publication {publication}.
        slots:
          content_tags: query.content_tags[]
          publication: path.publicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/posts'].post
  update:
    x-apievangelist-phrasing:
      intent: Create a newsletter post
      effect: write
      questions:
      - How do I create and schedule a newsletter issue through the API?
      - Can I start a new post from one of my post templates?
      - Which plans are allowed to create posts programmatically?
      instructions:
      - text: Create a post titled {title} on publication {publication}.
        slots:
          title: requestBody.title
          publication: path.publicationId
      - text: 'Draft a new post {title} with this content: {body_content}.'
        slots:
          title: requestBody.title
          body_content: requestBody.body_content
      - text: Create post {title} and schedule it to send at {scheduled_at}.
        slots:
          title: requestBody.title
          scheduled_at: requestBody.scheduled_at
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/posts/{postId}'].get
  update:
    x-apievangelist-phrasing:
      intent: Get one post
      effect: read
      questions:
      - Can I fetch a single post and its content by ID?
      - Why does a post I just created return still-being-created?
      instructions:
      - text: Get post {post} on publication {publication}.
        slots:
          post: path.postId
          publication: path.publicationId
      - text: Show post {post} with its {expand} included.
        slots:
          post: path.postId
          expand: query.expand
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/posts/{postId}'].delete
  update:
    x-apievangelist-phrasing:
      intent: Delete or archive a post
      effect: destructive
      questions:
      - How do I delete a draft post I don't need?
      - What happens when I delete a post that has already been sent?
      instructions:
      - text: Delete post {post} from publication {publication}.
        slots:
          post: path.postId
          publication: path.publicationId
      - text: Archive sent post {post}.
        slots:
          post: path.postId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/posts/{postId}'].patch
  update:
    x-apievangelist-phrasing:
      intent: Update an existing post
      effect: write
      questions:
      - How do I change the title or subtitle of an existing post?
      - Can I reschedule a post that's already been created?
      instructions:
      - text: Change the title of post {post} on {publication} to {title}.
        slots:
          post: path.postId
          publication: path.publicationId
          title: requestBody.title
      - text: Reschedule existing post {post} to go out at {scheduled_at}.
        slots:
          post: path.postId
          scheduled_at: requestBody.scheduled_at
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/posts/aggregate_stats'].get
  update:
    x-apievangelist-phrasing:
      intent: Get combined stats across all posts
      effect: read
      questions:
      - What are the total opens and clicks across all my posts combined?
      - Can I get aggregate post stats for only one author's posts?
      instructions:
      - text: Show aggregate stats across all posts on publication {publication}.
        slots:
          publication: path.publicationId
      - text: Get combined stats for posts by author {authors} on {publication}.
        slots:
          authors: query.authors[]
          publication: path.publicationId
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/posts/{postId}/test_sends'].post
  update:
    x-apievangelist-phrasing:
      intent: Send a test email of a post
      effect: write
      questions:
      - How do I email myself a test copy of a post before it goes out?
      - How many test sends do I have left today?
      instructions:
      - text: Send a test of post {post} on publication {publication} to {recipient_emails}.
        slots:
          post: path.postId
          publication: path.publicationId
          recipient_emails: requestBody.recipient_emails
      - text: Email a test copy of post {post} to {recipient_emails}.
        slots:
          post: path.postId
          recipient_emails: requestBody.recipient_emails
      method: generated
      generated: '2026-09-26'
- target: $.paths['/publications/{publicationId}/posts/{postId}/preview'].get
  update:
    x-apievangelist-phrasing:
      intent: Generate a preview link for a post
      effect: read
      questions:
      - How can I see what a post looks like to premium subscribers before sending?
      - Can I preview a post as it will appear on the web versus in email?
      instructions:
      - text: Generate a preview URL for post {post} on publication {publication}.
        slots:
          post: path.postId
          publication: path.publicationId
      - text: Preview post {post} as a {subscriber_type} subscriber on {platform}.
        slots:
          post: path.postId
          subscriber_type: query.subscriber_type
          platform: query.platform
      method: generated
      generated: '2026-09-26'