beehiiv

Delete a podcast episode and its audio files. A published episode disappears from the show's RSS feed. This cannot be undone through the API.

delete_podcast_episode

Delete a podcast show and all of its episodes. The show's RSS feed stops serving. This cannot be undone through the API.

delete_podcast_show

Derive a complete BrandSpec from this publication's own brand - its web theme colors, fonts, name, and logo - via the template-builder factory. When the user wants pages composed in their existing brand, derive here first and pass the returned `brand_spec` through to `build_site_page` or `apply_site_package_draft`, adjusted or not. The derivation is deterministic and opinionated: the theme's five colors expand into the full 10-role palette with contrast-safe fallbacks (weak or missing colors are repaired), fonts map onto the editor's catalog, and three themes are generated. Palette, typography, and logo come from the publication; archetype, cards, motion, and copy land on neutral defaults - those are the user's creative choices, so adjust them conversationally before composing.

derive_brand_spec

Search the publications you could recommend, the same surface as the discover page in the app. Returns public-safe fields only. Use this to find a publication's ID before creating a recommendation. A publication that will pay you to recommend them carries an `offer`: - payout_per_lead_cents: what you earn per verified subscriber you send them, after the beehiiv cut. - eligible_countries: subscribers must be in one of these countries to be paid for. Empty means no restriction. - has_applied: you already have an open application to this offer. - auto_accepts_you: your publication already meets their auto-accept rules, so an application would go live immediately instead of waiting for review. Use type 'paid' to see only publications that pay, or 'free' for only those that do not. subscriber_count_at_least is a floor the app rounds down to, not an exact count.

discover_publications

Duplicate an existing post within its publication. Creates a new draft copy with " (N)" appended to the title, carrying over the body content, theme, audience targeting, content tags, and authors. The copy always starts as a draft - promotion/publish remains a human action via the beehiiv UI. Returns the new post in the same shape as `get_post`. To rename or change the copy, follow up with `edit_post`.

duplicate_post

Duplicate an existing post template into a new template in the same publication. The copy includes the template's content, theme, settings, and metadata, with "(N)" appended to its name. Discover template IDs with `list_post_templates`.

duplicate_post_template

Duplicate an existing product. Creates a draft copy with "(COPY)" appended to the name and a "-copy" slug, including its variant, pricing and redeemable.

duplicate_product

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`), then target a block in `operations`. Top-level blocks are stamped with `data-node-hash="<hash>"`; the response returns refreshed hashes so you can chain more edits without re-reading. A nested node is a valid target too - to change one paragraph inside a `section`, target that paragraph's `data-id` rather than replacing the whole section and re-sending its siblings. Target the hash by default: it is rejected if someone else changed that block since you read it, which an id is not. An edit elsewhere leaves a block's hash intact, so you can chain. Use an id when you mean to write over whatever the block now holds. `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 target no longer resolves, 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). Web metadata (title, subtitle, web and SEO settings, tags, authors) saves straight to the post, including already-published posts, so there is no publish step and nothing for a human to do in the beehiiv UI. Once a post has sent, the email subject line, email preview text, custom live URL, social share and email audience are locked and are rejected or ignored. 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` (body edits on a published post land in the draft until a human clicks Update web). 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`), then target a block in `operations`. Top-level blocks are stamped with `data-node-hash="<hash>"`; the response returns refreshed hashes so you can chain more edits without re-reading. A nested node is a valid target too - to change one paragraph inside a `section`, target that paragraph's `data-id` rather than replacing the whole section and re-sending its siblings. Target the hash by default: it is rejected if someone else changed that block since you read it, which an id is not. An edit elsewhere leaves a block's hash intact, so you can chain. Use an id when you mean to write over whatever the block now holds. Each block takes one operation per call, so a target may appear only once in `operations`. To replace a block and add content around it, put the extra blocks in that replace's `content`; for anything else, make a second call with the refreshed hash. 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 target no longer resolves, 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

Edit a post template's body incrementally by targeting individual blocks, or replace the entire body with `html_content`. For incremental edits, read the template once with `get_post_template_content` (each top-level block carries a `data-node-hash`), then target blocks in `operations`. Only the blocks you touch are re-parsed; untouched blocks survive byte-identical. Use `insertBefore`/`insertAfter` to place new content: `insertBefore` a block hash finds that block's position and prepends content before it. For full replacement, provide `html_content` - it replaces the entire body. Omit `operations` for full replace. `operations` and `html_content` are mutually exclusive; providing both raises an error. For supported HTML syntax and per-node parseHTML rules, call `learn_post_authoring`. Templates migrated from publication settings or created during onboarding are read-only. To update template metadata (name, subject line, etc.), use `edit_post_template` instead. For theme-level styling, use `save_post_template_theme`.

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, or OpenAI with model_preset "openai", 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

Get a publication's community: branding, sync toggles, tier gating, Luma calendar, and PWA. Returns `exists: false` when the publication has not created a community yet.

get_community

Get a community channel with its display position, default flag, and access gating: `gated` is true when members need a premium tier or a matching custom field value, and `tiers` lists the premium tiers required.

get_community_channel

Get a community member's profile, roles, and banned/removed status.

get_community_member

Get a publication's community overview metrics for a period: new members, posts created, comments and replies, and member participation, each with the period total and the previous period's total for comparison. Pass `breakdown` to drill into a ranked list instead of the overview: new_members (recent joiners), popular_channels, popular_members, or top_posts. For popular_channels/popular_members set `by` to rank by "posts" (default) or "comments".

get_community_metrics

Get a community post with its threaded comments and a summary of any attached content (embedded Post, Poll, Survey, or Podcast presented as type + id). Comments are paginated.

get_community_post

Get a scheduled community post with its full body as HTML, in the form schedule_community_post takes. Read a post before cancelling it to schedule it again, so its content carries over. A video in the post does not carry over: a post with a video can only be rescheduled in the beehiiv app. You read as your own community member, the one that joined with your beehiiv account's email, and that member must be a moderator or above. Otherwise the call returns "Access denied": tell the user to join the community with that email or to get a moderator role.

get_community_scheduled_post

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 the content gate settings for a page on a publication's website. Content gates hide content below the gate based on the visitor's subscription status. Reports the gate's type (inline or popup) and its audience settings. Identify the page with page_id, slug, or page_type; call list_pages to see them.

get_content_gate

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

Get a single group subscription: its tier, purchaser, seat counts, per-seat price, list price, the tier's current group discount (it can differ from the discount at purchase), billing dates and the custom deal it came from, if any. Use list_group_subscription_seats for its members.

get_group_subscription

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

Get the opt-in confirmation email for a publication. Returns the subject line, preview text, and content as editor HTML. Call save_opt_in_email to make changes. Pass format: 'html' for the full themed email render instead.

get_opt_in_email

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

get_order