beehiiv

Edit an existing automation email's body incrementally by targeting individual blocks - cheaper and safer than resending the whole body with `save_automation_email`. Untouched blocks are left exactly as they are; only the blocks you touch are re-parsed. Read the body once with `get_automation_email_content` (format: `editor_html`), which stamps each top-level block with `data-node-hash="<hash>"`, then target those hashes in `operations`. The response returns refreshed hashes so you can chain more edits without re-reading. `content` is HTML matching the editor's parse rules - the same contract as `save_automation_email`. Call `learn_post_authoring` for it. Automation emails drop ad-related editor nodes such as `advertisementOpportunity` rather than authoring them. Edits land in the automation's staging (draft) workspace. When the response reports the automation live with unpublished changes, relay its `publish_instructions`. Atomic: if any block hash no longer matches, nothing is applied and you are told to re-read.

edit_automation_email_content

Change an existing website page's metadata - its name, visibility, paywall, SEO/social cards, and layout toggles. This is a partial patch: only the fields you send change (e.g. send just `name` to rename, nothing else is touched). Send at least one of `name`, `page_enabled`, `premium`, `metadata`, or `customization` - identifying the page alone leaves nothing to change. To read a page without changing it, call `get_page`. Edits land on the page record directly; body content is versioned separately. For the full typed shapes (the `metadata` and `customization` objects) call `learn_page_metadata`.

edit_page

Change an existing post's metadata (title, subtitle, audience, settings, SEO, content tags). This is a partial patch - only the fields you send change (e.g. send just `title` to rename, nothing else is touched). Edits land in the post's draft - a human publishes in the beehiiv UI for changes to go live. For the full typed shapes (recipients, web/email/seo settings, content tags) call `learn_post_metadata`. To change the post's body, use `edit_post_content`. To create a new post, use `save_post`.

edit_post

Edit an existing post's body incrementally by targeting individual blocks - cheaper and safer than rewriting the whole body. Untouched blocks are left exactly as they are; only the blocks you touch are re-parsed. Read the body once with `get_post_content` (format: `editor_html`), which stamps each top-level block with `data-node-hash="<hash>"`, then target those hashes in `operations`. The response returns refreshed hashes so you can chain more edits without re-reading. When the body already has structure - a template scaffold, a sign-off/footer, or a placeholder section - place new content with `insertBefore`/`insertAfter` the relevant block, or `replace` the placeholder, rather than `insert position:"end"`, which lands content after the sign-off. `content` is HTML matching the editor's parse rules; call `learn_post_authoring` for the node and mark contract. Ad network opportunities and automated ad placements can be inserted - use the contract returned for `advertisementOpportunity` or `automatedAdvertisementPlacement`. Other editor-managed nodes already in the post (polls, sponsorships, and so on) round-trip fine, but adding or repointing them here needs their contract to say they are authorable. Atomic: if any block hash no longer matches, nothing is applied and you are told to re-read. Edits land in the draft only - a human publishes in the beehiiv UI.

edit_post_content

Update a post template's metadata. This is a partial patch - only fields you send are changed. To replace the template's body content, use `edit_post_template_content`. To create a new template, use `save_post_template`. Templates migrated from publication settings or created during onboarding are read-only.

edit_post_template

Replace a post template's body content. Provide the full body as HTML via `html_content` - it replaces the entire template body (not a partial patch). Read the current body first with `get_post_template_content` if you need to preserve existing content. To update template metadata (name, subject line, etc.), use `edit_post_template` instead. For supported HTML syntax and per-node parseHTML rules, call `learn_post_authoring`. The template's own fonts, colours, gridlines, and button design are theme-level; set them with `save_post_template_theme`. Templates migrated from publication settings or created during onboarding are read-only.

edit_post_template_content

Generate an AI image from a text prompt and save it to a publication's media library. Fire-and-forget: this enqueues a background job and returns immediately with a `generation_id` and status "pending". Kick it off, then continue with other independent work (other pages, content, assets), and call `get_image_generation_status` once you actually need the result. The finished asset's `id` serves as a post's `thumbnail_id`, and its `url` embeds in HTML content via `save_post` or `edit_post_content`. Generation uses Google Gemini and counts toward the workspace's AI credit quota, reported in the completed status response's `ai_usage` field.

generate_image

The full performance and payment report for one ad placement: earnings and payout status, payout model and rate, recipients and delivery rate, unique opens and open rate, payable clicks and click-to-open rate, and the send window. Get the report id from list_ad_reports.

get_ad_report

Get a single asset from the media library with full details including usage information

get_asset

Get an author's details by author ID

get_author

Get an automation's full configuration including triggers, step flow, email metadata, and branch paths. Use workspace parameter to inspect live (published) or staging (draft) flow.

get_automation

Get the rendered content of an automation step's email. 'editor_html' returns canonical HTML compatible with save_automation_email and, for small changes, edit_automation_email_content - each top-level block is stamped with data-node-hash for targeted patching. A 'staging' read falls back to 'live' when the step has no unpublished draft yet; the response 'workspace' field reports which was read. Call `get_automation_schema` for the full email workflow.

get_automation_email_content

Get detailed information about a single automation journey, including all journey steps, branch decisions, and per-subscriber email engagement metrics (open rate, click rate).

get_automation_journey

Get the Automation reference: trigger event main_conditions shapes, step type params, branch paths, resources, and email authoring workflow.

get_automation_schema

Get performance metrics for an automation. Returns overall stats, per-email breakdown, and optionally per-step subscriber counts with branch decisions. Rates are percentages.

get_automation_stats

Compare an automation's staging workspace against its live (published) version. Returns a summary of what changed: added, removed, or modified steps and triggers. Use before publishing to review pending changes.

get_automation_workspace_diff

Retrieve detailed information about a condition set, including its full definition

get_condition_set

Get the condition set schema: available condition types, attributes, operators, and structure.

get_condition_set_schema

Get AI crawler and bot analytics for a publication's website — total, served, and blocked requests, AI-crawler share, per-crawler breakdown, top crawled pages, and response status codes.

get_crawler_analytics

Get identity and access context for the authenticated user

get_current_user

Get a publication's revenue broken down by feature - ad network, boosts, paid subscriptions, and digital products - plus the combined total, over a time period or an exact date range.

get_earnings

Get email engagement metrics (opens, clicks) for a publication over time, broken down by period.

get_engagements

Check the status of an AI image generation started by `generate_image`: "pending", "processing", "completed" (the response then carries full asset details) or "failed" (with an error message). Finished responses also carry an `ai_usage` object reporting AI credit consumption. Generation typically takes 15-45 seconds, so do other independent work after kicking it off and check back once, rather than polling in a loop. When you do need to wait, leave about 10 seconds between checks.

get_image_generation_status

Retrieve detailed information about a newsletter list. subscriber_count reflects active members only; use list_newsletter_list_subscriptions (with the status filter) to see pending, inactive or paused members.

get_newsletter_list

Get an order's full details, including the buyer (subscription id, email, status), line items, refund status, and fulfillment status.

get_order

Get a website page's metadata and customization. Pass include_content: true to also fetch the body rendered as canonical dream HTML, from the draft by default or from what is live on the site with version: 'published'. That HTML leaves out card-layout attrs and a post feed's rebuilt `data` cache - read a block's own attrs with get_page_content. Large pages are split into chunks: each call returns one chunk plus total_chunks; request the next chunk while chunk < total_chunks.

get_page

Retrieve detailed information about a podcast episode

get_podcast_episode

Get performance metrics for a specific podcast episode — total downloads, unique listeners with period-over-period growth, plus top listening apps, countries, and cities by download volume. Returns all-time stats by default.

get_podcast_episode_stats

Retrieve the plain text transcript for a podcast episode

get_podcast_episode_transcript

Retrieve detailed information about a podcast show including categories, platform links, and episode count

get_podcast_show

Get performance metrics for a podcast show — total downloads, unique listeners with period-over-period growth, plus top listening apps, countries, and cities by download volume. Defaults to all-time stats; pass start_date/end_date for a custom range.

get_podcast_show_stats

Get a poll's details including choices and response counts

get_poll

Get a post's details including content, metadata, and configuration

get_post

Get the content of a post in a specified format (text, html, or editor_html), optionally simulating how it appears for different subscriber types

get_post_content

Read the publication's custom email footer - the block of content that renders at the bottom of every post's email, above the copyright line, mailing address, and unsubscribe link. `content` is canonical HTML in the shape `save_post_footer` accepts, so you can read it, change it, and send it straight back. Empty `content` with `active: false` means no footer has been written yet. This reads the publication-wide footer by default. Pass `post_theme_id` to read what a given theme renders, which is its own footer when it carries one and the publication's otherwise.

get_post_footer

Get performance metrics for a specific post — email delivery, open rate, click-through rate, bounce rate, unsubscribe rate, and web engagement.

get_post_stats

Get performance metrics for multiple posts in one call — per-post email delivery, open rate, click-through rate, unsubscribes, and web engagement. Returns a per-post summary; for the full single-post breakdown (bounce, suppression, split test) use get_post_stats.

get_post_stats_batch

Read a post template's body as canonical editor HTML - the shape `edit_post_template_content` accepts, so what you read here can be edited and sent straight back.

get_post_template_content

Get a single paid subscription offer, including its terms, the tiers and billing cadences it applies to, and how many times it has been redeemed. An empty tiers list means the offer applies to every tier, and an empty plans list means it applies to every billing cadence.

get_premium_offer

Get a product's full details including variants, tags, and sales totals

get_product