add_automation_step
ChatGPTAdd a single step to an existing automation's flow. Works on live (published) automations: the step is added to a staging workspace (a draft copy) and only affects the live automation once you publish. Reference the parent step via parent_id; live step IDs are accepted and mapped to their staging copy. Call get_automation_schema for per-step-type param shapes. For send_email, pass subject_line to auto-create a placeholder email, or email_message_id to attach an existing one. Configure a webhook step's destination with update_automation_step after creating it. When the response reports the automation live with unpublished changes, relay its publish_instructions.
add_segment_to_newsletter_list
ChatGPTAdd every subscriber in a segment to a newsletter list. Runs in the background against the segment's current members. Poll get_subscription (with include_newsletter_lists) or the list's list_subscriptions to confirm membership.
apply_to_paid_recommendation
ChatGPTApply to a paid recommendation offer, asking that publication for permission to recommend them to your subscribers in exchange for a payout per subscriber you send them. Find offer_id with discover_publications - it is the offer.id on a publication that pays to be recommended. Applying normally puts nothing in front of your subscribers yet: the offer's owner reviews the application, and only an accepted one becomes a live recommendation. The exception is an offer whose offer.auto_accepts_you is true, which accepts on submission and starts recommending them to your subscribers straight away - confirm with the publisher before applying to one of those. Track an application with list_paid_recommendation_applications; once accepted it appears in list_recommendations with boosted: true. message is the pitch the reviewer reads, so say who your audience is and why they are a good match. The reviewer sees only your message and your publication, so applying without one gives them nothing to judge. Each publication can only submit a limited number of applications per month, and only one application per offer at a time.
build_site_page
ChatGPTCompose a single website page using the template-builder factory (tb) - deterministic, rule-validated output - and write it as that page's DRAFT content. The live published page is never changed; a human promotes via the beehiiv advanced builder. category must match the identified page's actual category, which guards against overwriting e.g. a home page with archive-shaped content. If tb's page-scoped rules report errors they come back so you can adjust the spec and retry.
delete_automation_step
ChatGPTDelete a single step from an existing automation's flow. Works on live (published) automations: the deletion is applied to a staging workspace (a draft copy) and only affects the live automation once you publish. The step's children are re-parented automatically. Pass the live or staging automation_step_id to delete. Live IDs are mapped to their staging copy. When the response reports the automation live with unpublished changes, relay its publish_instructions.
delete_automation_trigger
ChatGPTDelete a trigger from an automation. Always edits a staging workspace (a draft copy); the live automation is unchanged until a human publishes from the editor. Pass the live or staging automation_trigger_id to delete. Live IDs are mapped to their staging copy. An automation must keep at least one trigger. The deletion is saved to staging; publish the changes from the editor.
delete_podcast_episode
ChatGPTDelete 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_show
ChatGPTDelete a podcast show and all of its episodes. The show's RSS feed stops serving. This cannot be undone through the API.
derive_brand_spec
ChatGPTDerive 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.
discover_publications
ChatGPTSearch 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.
duplicate_post
ChatGPTDuplicate 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_template
ChatGPTDuplicate 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_product
ChatGPTDuplicate an existing product. Creates a draft copy with "(COPY)" appended to the name and a "-copy" slug, including its variant, pricing and redeemable.
edit_automation_email_content
ChatGPTEdit 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_page
ChatGPTChange 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_post
ChatGPTChange 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_content
ChatGPTEdit 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. 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_template
ChatGPTUpdate 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_content
ChatGPTReplace 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.
generate_image
ChatGPTGenerate 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.
get_ad_report
ChatGPTThe 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_asset
ChatGPTGet a single asset from the media library with full details including usage information
get_author
ChatGPTGet an author's details by author ID
get_automation
ChatGPTGet 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_email_content
ChatGPTGet 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_journey
ChatGPTGet 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_schema
ChatGPTGet the Automation reference: trigger event main_conditions shapes, step type params, branch paths, resources, and email authoring workflow.
get_automation_stats
ChatGPTGet 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_workspace_diff
ChatGPTCompare 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_condition_set
ChatGPTRetrieve detailed information about a condition set, including its full definition
get_condition_set_schema
ChatGPTGet the condition set schema: available condition types, attributes, operators, and structure.
get_content_gate
ChatGPTGet 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_crawler_analytics
ChatGPTGet 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_current_user
ChatGPTGet identity and access context for the authenticated user
get_earnings
ChatGPTGet 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_engagements
ChatGPTGet email engagement metrics (opens, clicks) for a publication over time, broken down by period.
get_group_subscription
ChatGPTGet a single group subscription: its tier, purchaser, seat counts, price, billing dates and the custom deal it came from, if any. Use list_group_subscription_seats for its members.
get_image_generation_status
ChatGPTCheck 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_opt_in_email
ChatGPTGet 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.
get_order
ChatGPTGet an order's full details, including the buyer (subscription id, email, status), line items, refund status, and fulfillment status.
get_page
ChatGPTGet a website page's metadata and customization. Read the page's body with get_page_content.
get_page_content
ChatGPTOn a website builder site, call it with just the page identifier: it returns an editable list of the nodes you may change, with the template value in attrs and the publisher's edit, if any, in override - what the page shows. A scope: "site" row is shared by every page. Only what would publish is listed, so a post feed with no posts is left out until it has content. Everything below describes an advanced builder site. Read a website page's body. format: "html", the default, renders it under html for reading, each top-level block stamped with its data-node-hash; it omits card-layout attrs and a feed's rebuilt data. format: "json" returns native Tiptap JSON - the format save_page_content writes - so read with it before editing. Passing node_id, node_hash or block_hash reads json, whatever format says. A raw-HTML page returns its HTML verbatim in either format, the format save_page_html writes. The rest describes json. Every node, nested or not, is addressable by its attrs.id or its _hash, here and in save_page_content. Prefer the id for anything you intend to edit later: a hash is a digest of the node's bytes, so it retires the moment anything inside it changes - including one you did not make, since the editor re-saves the page whenever a human touches it. Use the hash when a write should fail if the block moved under you. Small docs return whole. Larger ones come back as an index of blocks (hash, id, type, chars); type and chars tell you which blocks the request concerns. A node still too large returns its own children index to drill into. A truncated response names the way to get the rest: next_offset, unfetched, attr_chars. A dynamic element (post feed, pricing, authors) keeps its per-card render template in structureTiptapState/structureTiptapStateDraft, returned as an __elided__:... marker. Pass the marker back untouched and save_page_content restores it; omitting the attr keeps it too. That template renders the cards, so sibling style attrs (titleFontSize, titleTextColor...) only reach what it leaves to inherit - a missing change lives inside it, so reveal it and edit it there. A post, products or podcast feed's data (selectedPodcastShowEpisodes on a podcast feed) is elided the same way: the server rebuilds it on every page load, so what it stores is its last render. Change what a feed shows through its group, filter and count attrs; reveal data only to edit a pinned selection.
get_podcast_episode
ChatGPTRetrieve detailed information about a podcast episode
get_podcast_episode_stats
ChatGPTGet 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_transcript
ChatGPTRetrieve the plain text transcript for a podcast episode
get_podcast_show
ChatGPTRetrieve detailed information about a podcast show including categories, platform links, and episode count
get_podcast_show_stats
ChatGPTGet 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_poll
ChatGPTGet a poll's details including choices and response counts
get_post
ChatGPTGet a post's metadata and configuration. Read its body with get_post_content.
get_post_content
ChatGPTGet 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_stats
ChatGPTGet performance metrics for a specific post — email delivery, open rate, click-through rate, bounce rate, unsubscribe rate, and web engagement.
get_post_stats_batch
ChatGPTGet 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_template_content
ChatGPTRead 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_theme
ChatGPTRead the theme design tokens a post renders with - fonts, colors, spacing, borders and backgrounds across text, tables, buttons, quotes, images and layout. tokens is the same map save_post_theme accepts, so you can read it, change one key, and send it straight back. source tells you where the theme comes from: post when the post carries its own override, publication_default when it is still riding the publication's theme and every publication change moves it too. A post created without a template inherits silently, so check source before a send. This reads the post's own styling. learn_post_authoring reports the publication default and the token vocabulary.
get_premium_offer
ChatGPTGet 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_product
ChatGPTGet a product's full details including variants, tags, and sales totals
get_product_review_settings
ChatGPTGet product review moderation and display settings for a publication
get_publication
ChatGPTGet a publication's profile and configuration. Admins also see each web domain, email domain, web redirect, and branded link with the status shown in domain settings.
get_publication_settings
ChatGPTGet the publication settings that save_publication_settings accepts. Only settings currently available to this publication are returned, and the document is safe to round-trip unchanged.
get_publication_stats
ChatGPTGet a high-level overview of publication performance — active subscribers, engagement rates, subscriber growth, earnings, and top acquisition sources.
get_recommendation_partner_insights
ChatGPTGet engagement and spend insights for a publication's paid recommendation partners (publications you pay to recommend you), to identify which send high-quality, engaged subscribers and which underperform or should be canceled. Returns totals plus partners ranked by subscribers gained and by open rate (both top and under performers), and the single highest-growth and highest-paid partners. A partner needs at least 10 subscribers gained in the period to be ranked. Pass recommendation_id (the 'id' from list_recommendations with direction 'incoming') to also get that partner's figures as partner. Its status_counts split subscribers gained in the period: - verified: passed verification and were paid for. - pending: still in the verification window, including escrowed signups. - failed: did not pass verification and were not paid for. - pending_opt_in: have not confirmed a double opt-in subscription yet. - free: gained without a verification status. - deleted: acquired, then deleted. status_counts, open_rate and the engagement, blocked-by-country and total-subscriber figures need the recommendations network UI on the publication. Without it, partner carries the legacy all-time figures only. Rates are percentages from 0 to 100.
get_referral_program
ChatGPTGet a publication's referral program details, including milestones and rewards
get_segment
ChatGPTRetrieve detailed information about a segment
get_segment_schema
ChatGPTGet the Segment DSL reference: available fields, operators, syntax, and examples.
get_site
ChatGPTGet a publication's website structure, content index, and configuration. Returns site metadata, SEO, social links, analytics pixels, settings, content (posts, authors, categories, products, podcast episodes, forms), fonts, and redirects. Two keys cover the site outside its pages: theme holds the fonts and colors every page, global and post list inherits, and globals names the navbar/footer/modal documents, which the page tools cannot reach. A publication on the legacy website builder has no site these tools can read.
get_site_global
ChatGPTGet one of a website's site globals (navbar, footer, login_modal, signup_modal). Reads the draft you are editing, or pass site_version_id from list_site_versions to read what an earlier version held. Use save_site_global to write it back. Every node carries a _hash, and most carry an attrs.id: either addresses that node in a save_site_global operations edit, and an id survives a rewrite where a hash does not. A navbar's two trees are under attrs.data.desktop and attrs.data.mobile, not in content, and they mirror ids - so an operation on a navbar names its viewport. A website builder site draws its chrome from a preset, so there is no document: any valid key returns one editable list covering the navbar, footer and subscribe form together, read from the draft. Write each back with save_site_global overrides, under its key where it has one, else its id.
get_skill
ChatGPTGet an agent skill with its instructions, such as brand guidelines.
get_subscribe_form
ChatGPTGet a subscribe form's settings, theme design tokens (a flat token map matching save_subscribe_form_theme's input), and custom field bindings. Returns unpublished draft edits when present, otherwise the live theme.
get_subscribe_form_diff
ChatGPTCompare a subscribe form's unpublished draft against its live theme. Lists every token that differs (live vs draft value) - i.e. exactly what publishing the draft from the website editor would change. Returns no changes when there is no draft.
get_subscriber_growth
ChatGPTGet day-by-day subscriber growth for a publication: new subscribers, unsubscribes, and net change per day, matching the Subscriber Growth chart on the dashboard. Defaults to the last 28 days. For the total active subscriber count over time, use get_subscriber_history.
get_subscriber_history
ChatGPTGet the publication's active subscriber count over time, matching the values shown in the dashboard's subscriber growth chart. Use this for historical or trend questions such as "how has my list grown year over year?" or "what did my subscriber count look like last quarter?"; for one window's totals and rates rather than a series, use get_publication_stats; for daily new subscribers and unsubscribes, use get_subscriber_growth. Each entry is the count as of that date, so the entry dated 2025-01-01 is the count at the end of 2024. The final entry is the count right now.
get_subscription
ChatGPTGet a subscription's details by subscription ID
get_subscription_batch
ChatGPTGet full details for multiple subscriptions in one call — email, status, tags, tiers, custom fields, and per-subscriber engagement stats. Returns a per-subscription entry plus a not_found list. For a single subscriber use get_subscription.
get_survey
ChatGPTGet a survey's details including questions, options, and aggregate response data
get_tier
ChatGPTGet a tier's details by tier ID
get_website_analytics
ChatGPTGet the high-level website analytics overview for a publication.
get_website_analytics_breakdown
ChatGPTGet a ranked website analytics breakdown grouped by dimension. The data block is keyed by the underlying metric (e.g. data.page_views or data.sessions).
get_website_analytics_conditions_schema
ChatGPTGet the schema for website analytics conditions, used to build the conditions parameter for website analytics tools.
get_workspace
ChatGPTGet details about the current workspace, including whether beehiiv has disabled its sending or disabled or frozen its paid recommendations
learn_page_authoring
ChatGPTFor an advanced builder site. A website builder site has no node tree to write - it takes overrides on save_page_content and save_site_global, whose descriptions list every type and attr it stores. The raw node contract behind save_page_content, in native Tiptap JSON - the exact shape it writes, so every example pastes straight into an operation. It is generated from the dream-editor Tiptap schema dump, so it cannot drift from the editor. This is the escape hatch, and the reference for a patch path. Compose from the primitives and recipes instead (learn_site_design topic: 'composition', if not already in your context); they derive the mechanics from the publication's brand so you write the idea, not the expansion. Reach here for a design the builders cannot express, or to look up an attribute you are patching. No args returns a TOC of every node and mark with attribute names, plus the list of page_categories. Pass node: <name> for the full attribute table, or category: <value> (e.g. 'home', 'authors-show') for that page's required dynamic nodes, which auto-fill with live data, its record_bindings, the attrs.mergeTag values that bind ordinary nodes to the record a dynamic page renders, and a worked example derived from the editor's own default content. Drop a binding and the page keeps rendering, showing your placeholder copy on every record.
learn_page_metadata
ChatGPTReference for the page metadata accepted by edit_page - name, visibility, paywall, the SEO/social-card metadata object, and the layout customization object.
learn_post_authoring
ChatGPTLearn the canonical HTML contract used by save_post and edit_post_content for a specific publication. Returns a TOC of every node and mark with example HTML and attribute names, plus the publication's valid merge tags ({{tag_name}} patterns) - enough to start writing without follow-up calls. Pass node: <name> for that node's parseHTML rules and full attribute table. Plan-gated widgets carry an available flag reflecting this publication's plan. Authorable ad network nodes include an example and placement instructions. Non-authorable nodes return a note and a null example: forbidden nodes are rejected on save, while other editor-managed widgets are accepted but will not render as authored - author those in the beehiiv editor. For typed config (recipients, web/email/SEO settings, content tags) call learn_post_metadata instead.
learn_post_metadata
ChatGPTReference for the typed config accepted by save_post (on create) and edit_post (on edit) — recipients, web/email/seo settings, content tags, and other top-level options. Mirrors the public Create/Update Post endpoints. For HTML/content shape, call learn_post_authoring instead.
learn_site_design
ChatGPTDesign intelligence for building beautiful beehiiv site pages - read overview first, then topic deep-dives; content is generated from the template-builder's rulebook and knowledge base.
learn_subscribe_form_authoring
ChatGPTReference for editing subscribe forms: the draft/publish workflow, allowed render and trigger values, trigger_config shapes, and the full theme token vocabulary grouped by section. Read this before calling save_subscribe_form or save_subscribe_form_theme.
list_ad_offers
ChatGPTThe ads a publication can currently place in a post: 'available_offers' (unclaimed offers the publisher hasn't acted on) and 'pending_opportunities' (offers already claimed but not yet placed). Embed an item's id using an advertisementOpportunity node via save_post or edit_post_content. When an offer lists more than one entry in 'creative_variations', let the publisher pick which they want (with logo vs without) and set data-advertisement-kind to their choice. Optionally set data-custom-intro to plain text shown before the ad when the custom ad intro feature is available. Ids are internal placement handles - build the node with them and refer to ads by advertiser name when talking to the publisher. For the history of opportunities already acted on, use list_ad_opportunities.
list_ad_opportunities
ChatGPTA publication's ad opportunity history - opportunities already acted on (accepted, pending, rejected, expired, canceled, missed). Use it to check the status of a past opportunity or find an already-accepted one to embed. Ids are internal placement handles; refer to ads by advertiser name when talking to the publisher. For the ads currently available to place, use list_ad_offers.
list_ad_reports
ChatGPTWhat a publication earned from the beehiiv ad network, post by post. One row per ad that has run, with the post it appeared in, the advertiser, how much it earned, and whether that money is paid or still awaiting approval. Use it to answer which posts made money and how much, to compare advertisers, or to total earnings per advertiser over a past month for finance reconciliation. In disbursement_status, paid and manual both mean settled; every other value is still pending. Returns all reports by default, newest send first. Use get_ad_report for one placement's full performance breakdown, get_earnings for publication-wide revenue totals across all monetization, and list_ad_offers for ads still available to place.
list_assets
ChatGPTSearch and browse a publication's media library. Supports text search, file type filtering, and folder filtering. Use an asset's url when placing it in post or page content, since the editor re-uploads images from any other host. share_url is a CDN link for sharing outside beehiiv.
list_authors
ChatGPTList authors for a given publication
list_automation_emails
ChatGPTList the emails sent by an automation. Use this to discover send_email step IDs before calling save_automation_email or get_automation_email_content.
list_automation_journeys
ChatGPTList subscriber journeys for a given automation with optional filtering by status, email, and time period. Returns journey details with cursor-based pagination. Use the next_cursor value to fetch subsequent pages.
list_automations
ChatGPTList automations for a given publication with optional filtering by state and trigger event
list_condition_sets
ChatGPTList condition sets for a publication, with optional filtering by status
list_content_tags
ChatGPTList and search content tags for a given publication
list_custom_fields
ChatGPTList custom fields for a given publication with optional filtering by kind
list_group_subscription_deals
ChatGPTList a publication's custom group subscription deals: negotiated seat counts and prices offered to one organization through a purchase link or invoice. A redeemed deal links to the group subscription it created (see get_group_subscription). These are not paid subscription offers (see list_premium_offers).
list_group_subscription_seats
ChatGPTList the seats of one group subscription: who was invited, who filled a seat, and who left. subscription_id is set once a seat is filled; pass it to get_subscription for the member's subscriber record.
list_group_subscriptions
ChatGPTList a publication's group subscriptions: one purchaser buys a block of paid seats on a tier and invites members to fill them. Each result includes the tier, seat counts, price, billing status and the custom deal it came from, if any. display_status is the status shown in the dashboard; status is the stored billing state. Use list_group_subscription_seats for the members of one group. Individual paid subscribers are in list_subscriptions, and tier pricing is in list_tiers.
list_orders
ChatGPTList orders (purchases) for a publication with optional filtering and pagination. Each order includes the buyer (subscription id, email, status) that placed it, so you can answer questions like 'who bought this product?' or 'what has this subscriber bought?'
list_page_versions
ChatGPTList one page's body history, newest first. Address the page by page_id, slug or page_type, the same way edit_page and save_page_content do. Every content write leaves a version behind, so this is how you find what a page looked like before a change - including changes from earlier turns. restorable is false for the draft. Pass an id from here to restore_version to put that body back. Bodies are not returned here because they are large - pass an id to get_page_content to read one first.
list_pages
ChatGPTList a publication's website pages (home, subscribe, custom pages, etc.) with their slugs, metadata, and publish state. Use get_page_content to read a single page's body.
list_paywalls
ChatGPTList paywall configurations for a given publication. Each paywall has a unique ID that can be used with save_post or edit_post_content to insert a specific paywall break via data-id.
list_podcast_categories
ChatGPTList the Apple Podcasts categories and subcategories available for podcast shows. Use the returned ids with save_podcast_show's categories parameter.
list_podcast_episodes
ChatGPTList episodes for a podcast show with optional filtering by status
list_podcast_shows
ChatGPTList podcast shows for a given publication with optional filtering by status
list_poll_responses
ChatGPTList individual poll responses showing which subscribers voted for which choice
list_polls
ChatGPTList polls for a given publication with optional filtering by status and type
list_post_click_subscribers
ChatGPTList subscribers who clicked links in a post, with each subscriber's acquisition channel and source. Omit url_hash to return every click across all the post's URLs in one pass (each row includes its own url); or pass a url_hash from list_post_clicks to scope to a single URL. Returns individual subscriber clicks with timestamps.
list_post_clicks
ChatGPTGet per-link click breakdown for a specific post. Returns individual URL click counts (email and web) rather than aggregate post-level stats.
list_post_subscriber_engagement
ChatGPTList per-subscriber engagement for a post. Each row reports a subscriber's status, their total opens and clicks, and the subscriber's acquisition channel and source. Each subscriber gets one status, ranked unsubscribed > clicked > opened > delivered, so a clicker reads as clicked and never as opened, and anyone who unsubscribed from this post reads as unsubscribed whatever else they did. Pass statuses: ["opened", "clicked", "unsubscribed"] for everyone who engaged with the post, ["clicked"] for everyone who clicked any link, and ["delivered"] for everyone who was sent it and did nothing.
list_post_templates
ChatGPTList post templates for a given publication
list_posts
ChatGPTList posts for a given publication with optional filtering by status and content tags
list_premium_offers
ChatGPTList a publication's paid subscription offers - percent discounts, free trials and paid trials that convert readers into paying subscribers. An offer with an empty tiers list applies to every tier, and an empty plans list applies to every billing cadence. These are not ad network offers (see list_ad_offers) or storefront product coupons (see list_product_coupons).
list_product_coupons
ChatGPTList and filter publication discount codes using the same controls and fields as the products UI
list_product_promotion_codes
ChatGPTList promotion codes, including deleted codes, for a publication-scoped product coupon
list_product_reviews
ChatGPTList and filter publication product reviews using the same controls and fields as the reviews UI
list_product_tags
ChatGPTList and search publication product tags with assignment counts
list_products
ChatGPTList products for a given publication with optional filtering and sorting
list_publication_tags
ChatGPTList the beehiiv publication-category names accepted by save_publication_settings' general_info.tags field.
list_publications
ChatGPTList all publications the authenticated user has access to
list_recommendation_suggestions
ChatGPTList AI-generated recommendation suggestions for a publication. Returns up to 4 high-quality publication suggestions that haven't been dismissed or already recommended.
list_recommendations
ChatGPTList a publication's recommendations, both free and paid. Defaults to outgoing recommendations (publications you recommend to your subscribers). Use direction 'incoming' to see which publications recommend you. Each recommendation includes: - boosted: true for paid recommendations, false for free ones. - status: the perspective-aware state shown in the UI - 'active', 'paused_by_you', 'paused_by_them', 'insufficient_funds', 'pending', or 'removed'. - referred_subscription_count: subscribers driven (outgoing) or gained (incoming) through the recommendation. - For paid recommendations only: cost_per_lead_cents, plus earnings_cents (outgoing, what you have earned) or spend_cents (incoming, what you have spent). referred_subscription_count mixes every subscriber state. For the outgoing verified, pending and failed split, read overview with direction 'outgoing': the all-time totals shown above this list in the app, where pending includes escrowed and amounts are formatted currency strings. The incoming overview carries spend totals instead. For one incoming partner's split, use get_recommendation_partner_insights with its recommendation_id. Change a free recommendation with save_recommendation, a paid one with save_paid_recommendation. Find publications you could recommend, free or paid, with discover_publications. Applications that have not been accepted yet are not recommendations - they live in list_paid_recommendation_applications.
list_referral_rewards
ChatGPTList rewards configured on a publication's referral program. Use reward IDs with save_referral_milestone.
list_segments
ChatGPTList segments for a publication
list_signup_flows
ChatGPTList signup flows for a publication. Each flow defines an ordered set of URLs that new subscribers step through. Returns the materialized steps with external/modal metadata.
list_site_redirects
ChatGPTList a publication's website redirects (old_path → new_path, status_code, redirect_type, wildcard, active). Redirects map old site paths to new ones. To create, update, or delete a redirect, use save_site_redirect.
list_site_templates
ChatGPTList the sections, blocks and pages this publication has saved as reusable templates from its own site - the user's own library, separate from the beehiiv template gallery. Use it when they name something of theirs ("my standard CTA", "that button I saved"), which is content they built rather than something to compose. Each entry carries id, name, description, level, category, and studio_default. studio_default is true for templates from The Atlas Collective, the package Studio onboarding preselects. The body stays out because you never need it: pass the id to save_page_content as an operation's site_template_id and it is spliced in server-side.
list_site_versions
ChatGPTList a website's version history: the site-wide snapshots and saves that cover the navbar, footer, modals, routes and settings. Newest first. For a snapshot, version sometimes names what triggered it (e.g. global_swap, theme_apply, agent_edit); most carry nothing, and some carry a human label. restorable is false for the draft, since that is the state you are editing. Pass an id from here to get_site_global to read what that version's navbar, footer or modals held, or to restore_version to roll the site back. For a single page's history, use list_page_versions instead - page saves are not reachable from a site version.
list_sites
ChatGPTList a publication's websites. The live one is the published site, the one visitors reach at the publication's domain; the rest are unpublished drafts nobody can see yet. Every other site and page tool takes the id from here as its site_id. builder is where a site's pages come from. Most sites are on website, the default: it assembles pages from a template as it renders, so what is stored is not what a visitor gets. advanced is opt-in and stores the pages it renders, so they can be read back and edited. A legacy publication has a site row that renders nothing a visitor ever sees. Each tool states which of these it works on.
list_skills
ChatGPTList the workspace's agent skills: saved instructions beehiiv's agent loads on demand, such as brand guidelines or house style. Workspace skills are shared with the team; private skills are visible only to their creator. Call get_skill for a skill's instructions.
list_subscribe_forms
ChatGPTList a publication's subscribe forms with summary metadata. Use get_subscribe_form for a form's full theme and custom fields.
list_subscriber_activity
ChatGPTList one subscriber's email activity across every post in the publication, most recent first. Each row gives the post, the event, when it happened, and for a click the URL that was clicked. Use this to build an interest profile for one subscriber from the posts they open and the links they click; for one post's whole audience use list_post_subscriber_engagement instead. event_type takes one value, so omit it to get opens and clicks together in one pass.
list_subscriptions
ChatGPTList subscriptions for a publication with optional filtering and pagination.
list_survey_responses
ChatGPTList individual survey responses with per-question answers
list_surveys
ChatGPTList surveys for a given publication
list_tags
ChatGPTList subscriber tags for a given publication
list_tiers
ChatGPTList tiers for a given publication with optional filtering by status
moderate_product_review
ChatGPTApprove or reject a subscriber-submitted product review. Only the moderation status can be changed - reviews are never created or edited through this tool, since the review text and score are subscriber-authored content.
open_beehiiv
ChatGPTOpen the beehiiv home app, which shows the user's default publication and suggested prompts they can send to this chat.
read_documentation
ChatGPTRead the full content of a documentation article, blog post, glossary term, or runbook by its ID
recalculate_segment
ChatGPTTrigger a recalculation of a dynamic or static segment to refresh its membership count and metrics. Recalculation runs in the background. Poll get_segment for status and num_members to track progress. Manual segments, and segments that are already recalculating, cannot be recalculated.
reorder_automation_steps
ChatGPTReorder automation steps in bulk. Pass bulk_updates keyed by live or staging automation_step_id. Each update can set parent_id, branch_arm, and branch_path_id; live IDs are mapped to their staging copies. When parent_id changes, the graph is automatically repaired: the moved step's old children are re-parented to its old parent, and the new parent's existing children are threaded under the moved step. Specify only the steps you are explicitly moving; displaced neighbours are updated automatically. Only works while the automation is not live. Changes are saved to staging; publish them from the editor.
restore_version
ChatGPTRoll a website back to an earlier version. Pass exactly one of site_version_id (from list_site_versions) or page_version_id (from list_page_versions). A site version restores the site-wide state - navbar, footer, modals, routes, settings - plus the body of every page it covers. A page version restores that one page's body; page history is not reachable from a site version, so undo a page write with page_version_id. The current state is backed up first, so a restore is itself undoable. Edits land in the draft only - a human promotes via the beehiiv advanced builder.
review_paid_recommendation_application
ChatGPTAccept or reject a pending application from a publication that wants to recommend you in exchange for a payout from your offer. Find application_id with list_paid_recommendation_applications using direction 'incoming', and read the applicant's audience quality with get_paid_recommendation_application first. Accepting starts a paid partnership: they begin recommending you to their subscribers straight away, and your offer's budget pays out for every verified subscriber they send. Confirm with the publisher before accepting on their behalf. Rejecting ends the application. The applicant is told, and rejected_reason is shown to them, so keep it civil and specific enough to be useful. Only pending applications can be reviewed. To pause or end a partnership you already accepted, use the paid recommendations dashboard in the app. save_paid_recommendation covers the other side only, the partnerships where you are the one recommending.
save_audio
ChatGPTUpload an audio file from a URL to a publication's media library. Returns the downloadable ID and metadata for embedding an audio widget via save_post or edit_post_content. Supported formats: MP3, WAV, OGG, FLAC, AAC, WebM audio.
save_automation
ChatGPTCreate or update an automation. Call get_automation_schema first for trigger event shapes, step type params, branch paths, and the resources map. - Create: omit automation_id. New automations start as draft; going live, pausing, and publishing stay human actions done in the editor. - Update metadata: pass automation_id with only the automation block. - Update a draft graph: pass automation_id with triggers and steps, which replaces the entire graph. Draft, never-published automations only. - Edit a published automation: its live graph cannot be replaced in place. Use add_automation_step, update_automation_step, delete_automation_step, or reorder_automation_steps for steps, and save_automation_trigger / delete_automation_trigger for triggers - these edit a staging copy, published from the editor. - Email content: send_email steps are created with placeholder content. Use save_automation_email afterwards to draft each step's body. When the response reports the automation live with unpublished changes, relay its publish_instructions.
save_automation_email
ChatGPTCreate or update the email for an automation's send_email step. Can be called multiple times - each call replaces the full content. Uses the same HTML syntax as post authoring - call get_automation_schema for the email workflow and learn_post_authoring for the full HTML reference. To start the email from a saved design instead of raw HTML, pass post_template_id (from list_post_templates) in place of html_content - this applies the template's body, theme, and sender settings. Provide at most one of the two. To change only the subject line, preview text or email settings, omit both and the body stays as it is. Edits always go to the automation's staging (draft) workspace. When the response reports the automation live with unpublished changes, relay its publish_instructions. For read-edit-save cycles, call get_automation_email_content with format: "editor_html" first, edit that HTML, then send it back here.
save_automation_trigger
ChatGPTCreate or update a trigger on an automation. Automations support up to 3 triggers (any of which can enrol a subscriber). Always edits a staging workspace (a draft copy); the live automation is unchanged until a human publishes from the editor. Omit automation_trigger_id to create, passing event and its main_conditions. Pass automation_trigger_id to update, where live IDs map to their staging copy and only the fields you send change. To replace all triggers on a draft automation at once, use save_automation. To remove a trigger, use delete_automation_trigger. The change is saved to staging; publish the changes from the editor.
save_condition_set
ChatGPTCreate or update a reusable condition set. Call get_condition_set_schema first to learn the available condition types, attributes, operators, and structure. Archived condition sets cannot be updated.
save_content_gate
ChatGPTUpdate the audience settings of an existing content gate on a publication's website page. Scope and limits: - Updates an existing gate only. save_page_content can insert a top-level contentGate node, but its body is yours to author and will not match a gate added in the website editor. - Changes who the gate applies to (show_when + tier) and toggles its popup. It does not edit the gated content, and it cannot author or restyle a popup's content. - Targets a single gate; it will not act on a page that has more than one content gate. Identify the page with page_id, slug, or page_type; call list_pages to see them.
save_content_tag
ChatGPTCreate or update a content tag used to organise posts on the website. If content_tag_id is provided, updates the existing tag; otherwise creates a new one. When updating, only the provided fields are changed - omitted fields keep their current values.
save_current_user
ChatGPTUpdate the authenticated user's own author profile: name, bio, avatar and social links. This writes the profile of the person whose credentials this session uses, and nothing else. It cannot edit another team member's profile: that profile belongs to that person and is shared across every publication they write for, so there is no admin path to it. To edit a byline the publication owns, use save_guest_author instead. Only the fields you pass are changed. Call get_current_user first to see what is already set. Social links must be full HTTPS URLs, e.g. https://linkedin.com/in/janedoe. Older profiles may hold links saved without a scheme; add https:// before passing one back.
save_custom_field
ChatGPTCreate or update a publication-level custom field used to capture extra data on subscribers. If custom_field_id is provided, updates the existing field; otherwise creates a new one. When creating, name and kind are required. The kind cannot be changed after creation.
save_file
ChatGPTUpload a file from a URL to a publication's media library. Returns the downloadable ID and metadata for embedding a fileAttachment widget via save_post or edit_post_content. Supported formats: PDF, EPUB.
save_guest_author
ChatGPTCreate or update a guest author (publication-scoped byline). If guest_author_id is provided, updates the existing guest author; otherwise creates a new one. When creating, publication_id and first_name are required. The maximum number of guest authors per publication is set by the workspace plan. Cannot create or modify User-typed authors (those require a full signup flow).
save_image
ChatGPTUpload an image to a publication's media library from a URL or raw base64 bytes. Returns the asset ID and the hosted image URL. The returned id can be used as a post's thumbnail_id. The returned url can be embedded in HTML content via save_post or edit_post_content.
save_newsletter_list_preference
ChatGPTCreate or update the subscriber preference-center entry for a newsletter list. Each list has at most one preference, shown in the subscriber preference center so subscribers can opt in/out of that list without unsubscribing entirely. If the list already has a preference, this updates it; otherwise it creates one.
save_opt_in_email
ChatGPTUpdate the opt-in confirmation email for a publication. Pass html_content to replace the body, subject_line to change the subject, and/or preview_text for the preview. Omitted fields remain unchanged. The confirmation button is automatic and will be added if missing from the HTML. Call get_opt_in_email to read the saved body.
save_page
ChatGPTCreate a new custom website page on a publication's site. The page is created as a draft with an empty body; promotion/publish stays a human action via the beehiiv UI. Compose the body with save_page_content, which is gated by the design rulebook. To change an existing page's metadata use edit_page. Only custom pages can be created - default and dynamic pages (home, subscribe, etc.) already exist. Provide slug (the page's URL path, unique on the site and not a reserved path) and name (its label). For a nested page, pass parent_path (e.g. ["blog"] places it at blog/<slug>). Pass uses_raw_html: true for a page whose body is hand-written HTML instead of composed blocks - the navbar and footer are hidden and you write it with save_page_html rather than save_page_content. This is one-way and cannot be changed afterwards, so only choose it for a design the builders cannot express; you give up the theming and responsiveness they derive from the publication's brand. Initial metadata (visibility, paywall, SEO/social cards, layout toggles) can be set in the same call via page_enabled, premium, metadata, and customization. Call learn_page_metadata for the full typed shapes.
save_page_content
ChatGPTOn a website builder site a page is assembled from a preset, so there is no body to compose. Send overrides there - a patch keyed by the node ids get_page_content returns - and ignore everything below, which describes an advanced builder site. Write a website page's DRAFT body. Provide exactly one of operations (targeted edits against nodes you read) or design (a tree of builders the engine expands against the publication's brand and validates in one hop). Edits land in the draft only - a human promotes via the beehiiv advanced builder. Design from learn_site_design (topic: 'composition') if that reference is not already in your context. Raw-HTML pages are not composable from blocks; write those with save_page_html. Reach for the smallest operation that expresses the change. Validation charges you only for the violations your edit adds, measured against the page as it stood before, so what you do not resend cannot be held against you: "just change the gradient" is a one-key set_attrs, while a wide replace makes you author of every attribute in that subtree and each one you drop is a new violation that blocks the save. A replace rejected over attributes you never meant to touch is a signal to retry as set_attrs on the node you actually meant. An __elided__:... marker from get_page_content (format "json") resolves back to its stored value on save, so pass it through untouched rather than substituting a value of your own. When the user names a template as theirs ("my standard CTA"), it is a saved one and list_site_templates has the id. A design replaces the entire body, so it must describe every section on the page: a one-node design discards every other block rather than adding that node. For an addition, a tweak, or "another one of these", use operations - which keeps the builders, since an operation can carry a design of its own. Saves are validated against the template-builder design rulebook and safe issues are autofixed, so the saved content may differ from what you submitted. Structural rules that would break the page reject the save with a violation list to adjust and retry; style findings return as suggestions, and issues the page already carried as pre_existing_issues - raise those if they help the user, and leave the page as it is otherwise. The response returns fixes_applied and refreshed block_hashes a follow-up edit can target with no re-read.
save_paid_recommendation
ChatGPTPause, resume, or end an existing paid recommendation - a publication you are being paid to recommend to your subscribers. Find the recommendation_id with list_recommendations; paid ones have boosted: true. This tool only works on paid recommendations - use save_recommendation for free ones. status options, the same ones save_recommendation and the app use: - 'inactive' pauses it, hiding the recommendation from your subscribers and stopping earnings. Reversible. - 'active' resumes a recommendation you paused. - 'archived' ends the partnership permanently. It cannot be undone, so confirm with the publisher first and prefer 'inactive' if they may want it back. list_recommendations labels these the way the app does, so a paused one reads back as 'paused_by_you' and an archived one as 'removed'. Creating a paid recommendation is not available here: a paid recommendation only exists once a publication accepts your application. Find publications that pay with discover_publications and apply with apply_to_paid_recommendation.
save_podcast_episode
ChatGPTCreate or update a podcast episode. If podcast_episode_id is provided, updates the existing episode; otherwise creates a new one. When creating, podcast_show_id and title are required. Setting status to 'scheduled' requires scheduled_at and an uploaded audio file (audio is uploaded through the dashboard). Changing scheduled_at on an already scheduled episode reschedules its publish job automatically. To unschedule an episode, set status back to 'draft'.
save_podcast_show
ChatGPTCreate or update a podcast show. If podcast_show_id is provided, updates the existing show; otherwise creates a new one. When creating, publication_id, title, description, and author are required. Setting status to 'active' publishes the show's RSS feed and requires artwork, at least one category, and at least one published episode.
save_poll
ChatGPTCreate or update a poll. If poll_id is provided, updates the existing poll; otherwise creates a new one. When creating, name, question, and choices (at least 2) are required. Published (locked) polls cannot be updated.
save_post
ChatGPTCreate a new draft post. Promotion/publish remains a human action via the beehiiv UI. To change an existing post's metadata (title, settings, audience) use edit_post; to change its body use edit_post_content. Call learn_post_authoring for the canonical HTML contract behind html_content. It is generated from the post-editor Tiptap schema, so it cannot drift from the editor, and patterns outside it may be silently dropped on parse. Call learn_post_metadata for the typed config - recipients, web/email/SEO settings, content tags. When post_template_id is provided the template's content prepends html_content, so your blocks land after the entire template. A default template is usually a complete scaffold - header, body placeholder sections, and a sign-off/footer - not just an intro, so appending html_content drops your content below the sign-off, which is rarely intended. For a structured template, omit html_content, then read the post with get_post_content (format: editor_html) and use edit_post_content to slot the body into place: replace the placeholder section, or insert before the sign-off. The template also seeds settings (theme, sender, footer) plus its content tags and guest authors, each of which the corresponding option field overrides.
save_post_template
ChatGPTCreate a new reusable post template with metadata and optional body content. To update an existing template's metadata, use edit_post_template. To replace its body, use edit_post_template_content. html_content is parsed into native editable blocks against the same contract as save_post. Call learn_post_authoring for that contract - a TOC of every node and mark, or node: <name> for one node's parseHTML rules and attribute table. It is generated from the post-editor Tiptap schema, so patterns outside it may be silently dropped on parse. The template's own defaults - fonts, text and link colours, table gridlines, button design - are theme-level; set them with save_post_template_theme.
save_post_template_theme
ChatGPTSet a post template's theme design tokens - fonts, colors, spacing, borders, and backgrounds across text, tables, buttons, quotes, images, and layout (the styling the editor's style sidebar controls). Pass theme_data as a partial map of token keys to values; only the keys you send change. Writes a per-template override seeded from the publication default, so the tokens you don't touch are preserved. Tables have no per-cell styling - set table_border_width: 0 here to remove gridlines. Call learn_post_authoring for the token vocabulary and current values (see its theme section). This is the post-template counterpart of save_post_theme.
save_post_theme
ChatGPTSet the theme design tokens for a single post - fonts, colors, spacing, borders, and backgrounds across text, tables, buttons, quotes, images, and layout (the styling the editor's style sidebar controls). This changes only the post you pass; the publication's theme and every other post are left untouched. Pass theme_data as a partial map of token keys to values; only the keys you send change. Writes a per-post override, forked from the publication default on first edit, so the tokens you don't touch are preserved. Read the post's current tokens back with get_post_theme. Tables have no per-cell styling - set table_border_width: 0 here to remove gridlines (inline style on a <td> is dropped on save). Call learn_post_authoring for the token vocabulary and current values (see its theme section). The footer_* tokens style the email footer; the footer's actual copy is separate - read and write it with get_post_footer / save_post_footer.
save_product
ChatGPTCreate or update a product (a paid or free offering buyers can purchase). If product_id is provided, updates the existing product; otherwise creates a new one. When creating, name and asset_id are required (upload the image first with save_image), plus the url or file_url for the chosen product_type. Updates change any product field; the redirect url can only be changed for link products.
save_product_review_settings
ChatGPTUpdate product review moderation and display settings for a publication. Lazy-creates the settings if this publication has none yet. Only the fields you pass are changed - omitted fields keep their current values.
save_product_tag
ChatGPTCreate or rename a product tag used to organize products. If product_tag_id is provided, renames the existing tag; otherwise creates a new one. Tag names are unique per publication (case-insensitive). To assign tags to a product, use assign_product_tags_to_product.
save_publication_settings
ChatGPTPartially update publication settings returned by get_publication_settings. Send only requested fields from its settings object. Omitted fields are unchanged; false and [] are real values; null clears only nullable fields.
save_recommendation
ChatGPTCreate, restore, update, or archive a free recommendation - a publication you recommend to your subscribers. Use discover_publications or list_recommendation_suggestions to find a recommended_publication_id first. The same (publication, recommended publication) pair is an upsert: an unknown pair creates a new recommendation, an existing one is updated. Omit reason to keep the current reason. Set status "inactive" to remove a recommendation (there is no delete - removed recommendations are kept inactive and can be restored). A publication can only have a limited number of active recommendations. To replace one when at the limit, set status "inactive" on an existing recommendation (see list_recommendations) before adding the new one. reason is shown to your subscribers, so write quality copy (max 500 characters). This tool only manages free recommendations. For paid ones (boosted: true in list_recommendations), use save_paid_recommendation to pause, resume, or end them.
save_referral_milestone
ChatGPTCreate or update a referral program milestone. Milestones define thresholds (e.g. 5 referrals) that trigger a reward email. Each milestone requires a reward — use list_referral_rewards to find reward IDs. If milestone_id is provided, updates the existing milestone; otherwise creates a new one. num_referrals must be unique per referral program. html_content is the email body - HTML matching the editor's parse rules (call learn_post_authoring for the node/mark contract). The milestone editor supports a subset of the post editor: ads, polls and dynamic content are dropped, not authored here. If the reward's type is promo_code, the body must contain the {{reward_promo_code}} merge tag.
save_referral_program
ChatGPTUpdate a publication's referral program settings. The referral program must already exist. Use get_referral_program to retrieve current settings. Only provided fields are updated — omitted fields keep their values. Pass enabled: false to disable the program, enabled: true to re-enable it.
save_referral_reward
ChatGPTCreate or update a referral program reward. If reward_id is provided, updates the existing reward; otherwise creates a new one. When updating, only provided fields are changed. Rewards are referenced by milestones — use list_referral_rewards to see existing rewards. Note: promo code file uploads are not supported via MCP; use the beehiiv dashboard for those.
save_segment
ChatGPTCreate or update a subscriber segment. Call get_segment_schema first to learn available fields and syntax. If segment_id is provided, updates the existing segment; otherwise creates a new one. When creating, name and where are required. If conditions change, the segment is reprocessed.
save_signup_flow
ChatGPTCreate or update a publication's signup flow - an ordered set of URLs that new subscribers step through. Omit signup_flow_id to create, where the first flow on a publication is automatically marked default. Pass it to update, where only the fields you send change. urls must be ordered: any external URL (a URL outside the publication's domain) has to be last. Each url must be a valid HTTP(S) URL. Setting default: true makes this the publication's default flow and unsets the previous default.
save_site_global
ChatGPTOn a website builder site the navbar, footer and subscribe form come from a preset, so there is no document to compose. Send overrides there - a patch keyed as get_site_global returns them - and ignore everything below, which describes an advanced builder site. Write one of a website's DRAFT site globals - the navbar, the footer, or the login/signup modals. Pick it with key, and provide exactly one of operations, a design, or content. For an addition, a tweak, or "another one of these", use operations: targeted edits against the nodes get_site_global returned. An operation carries a design of its own, so you keep the builders and keep the rest of the global. A design composes the whole global, so it describes every item, not just the new one. Let a builder emit the node tree either way - it cannot fail on a miscounted bracket and the payload is a fraction of the JSON. Builders and their arguments are learn_site_design (topic: 'builders'). Content mode is the escape hatch for a shape no builder covers; read get_site_global first so you edit the shape the renderer expects. The navbar takes desktop and mobile, each {left, middle, right}. Its two trees are independent and mirror each other's node ids, so a design places every item into both and an operation names the viewport it edits. The footer and the modals take a flat design list: a footer composes into its sections, a modal into its body, wrapped in the login/signup shell for you. A footer background image goes on its section's attrs (backgroundImage, backgroundDarken, overlayColor), not the doc root. A modal needs a loginForm (or signup) and a modalSwitchLink to pass its own rules. Saves run the template-builder rulebook and safe issues are autofixed. A violation rejects the save with the list to adjust and retry; findings the global already carried return as pre_existing and never block. Edits land in the draft - a human promotes via the beehiiv advanced builder.
save_site_redirect
ChatGPTCreate or update a publication's website redirect, mapping an old site path to a new one. Omit site_redirect_id to create; pass it to update, where only the fields you send change. Both paths are on the publication's own site, because the site can only redirect within its own domain. Give new_path as a path that starts with /, such as /new-page or /blog?tag=news. old_path is normalised to a leading slash. A wildcard redirect is auto-detected when old_path contains *. Redirects are always permanent (HTTP 301).
save_site_settings
ChatGPTSet a website's builder-level settings. get_site returns the current values under settings, and only the settings you pass change. placeholder_data_enabled fills data-bound elements - post feeds, products, authors, testimonials - with sample records, so a publisher can see their design before they have real content. Recommend it when list_posts, list_products or list_authors show nothing to fill a feed with, and turn it on once the publisher agrees. It is the setting behind the builder's own "Enable placeholder data" and "Show placeholders" buttons. This is preview state: the published site never reads it, no page content changes, and turning it off restores the real feeds. The published-site equivalent is a post element's hasFakeData attribute, which does ship stock posts to readers - reach for this setting instead whenever the goal is to see a design. Say when you turn it on, and that real posts replace the samples once published.
save_site_theme
ChatGPTSet a website's theme tokens - the fonts, colors, borders and shadows the whole site renders from. Every page, the navbar, the footer, the modals and the post list read these, so a site-wide restyle belongs here: "change every font to Times New Roman" is one call setting header_font, body_font and button_font. Editing elements one by one misses every region that inherits the theme. Styling one element or one page stays a page edit. Pass preset to apply a curated theme by name. Each one is a whole look - palette, fonts and corner radius - whose text/surface pairings clear WCAG AA and whose fonts the builder already offers, so prefer a preset over inventing hex values when the ask is a mood ("make it neon", "something editorial") rather than a named color. Pass theme_data as a partial map of token keys to values; only the keys you send change. Send both to start from a preset and override part of it. get_site returns the current values under theme. The write carries into the draft pages and the globals as well, and snapshots the old theme so a human can undo it from the beehiiv advanced builder. The restyle is complete when this call returns, apart from anything holding a hand-set value of its own. The first write forks the publication's theme onto this site, leaving the publication's other sites untouched. A website-builder site takes this call too. There the write lands on the DRAFT theme and nothing reaches the live site until a human publishes. Its pages render from a preset, so there is nothing to carry the write into and no undo snapshot.
save_split_test
ChatGPTSet up an A/B test of email subject lines on a post that has not sent yet. The post's own subject line (email_settings.email_subject_line on save_post / edit_post) is the control; subject_lines are the alternatives tested against it, so each one must differ from it and from each other. This replaces the whole variant list: a subject line you omit is removed. Read the current list from get_post (split_test.subject_lines) and echo it back with your change. Only works while the test is still pending - once the post starts sending, the variants are locked. Results land in get_post_stats.
save_subscribe_form
ChatGPTCreate a new subscribe form, or update an existing one's name, success behaviour, and display rules. Pass subscribe_form_id to update an existing form (publication_id is not needed and is ignored if also given); pass publication_id alone to create a new form. name applies immediately; display and success settings write to the DRAFT and go live when it is published from the website editor. Edit visual design with save_subscribe_form_theme; see learn_subscribe_form_authoring for trigger_config shapes.
save_subscribe_form_theme
ChatGPTEdit a subscribe form's theme design tokens. Always writes the DRAFT theme - changes are not live until the draft is published from the website editor. Pass theme_data as a partial map of token keys to values (unspecified tokens are left untouched). Use reset_to_defaults to revert tokens to their default. Call learn_subscribe_form_authoring for the token vocabulary.
save_subscriber_tag
ChatGPTCreate or rename a subscriber tag. If tag_id is provided, updates the existing tag; otherwise creates a new one. When creating, publication_id and name are required. Tag names are normalized to lowercase and must be unique per publication.
save_survey
ChatGPTCreate or update a survey (form). If survey_id is provided, updates the existing survey; otherwise creates a new one. When creating, title is required. To publish, set status to "live" (requires at least one question with 2+ options for multiple choice). Use type to place the survey in a publication lifecycle slot (subscribe/unsubscribe/downgrade) or detach it (standalone).
save_survey_question
ChatGPTAdd or update a question on a survey. Use list_custom_fields to find valid custom_field_id values before adding questions. For multiple_choice or dropdown types, the custom field must be of kind "string" or "list". Pass options to set the answer choices for multiple_choice/dropdown questions, when adding or updating. Options are additive: listed values are added, existing ones are left untouched. Options for a list custom field are stored on the field, keeping it in sync. Set multi_select to true to let subscribers pick more than one answer. It is only valid for multiple_choice questions backed by a list custom field.
save_tier
ChatGPTCreate or update a paid tier's metadata (name, description, redirect URL, gifting). If tier_id is provided, updates the existing tier; otherwise creates a new one. When creating, name is required. Pricing is managed separately - use the beehiiv dashboard to add or change prices.
search_cashtags
ChatGPTSearch for stock/crypto tickers (cashtags) via StockTwits. Returns matching symbols that can be inserted as inline cashtag elements in post content via save_post or edit_post_content.
search_documentation
ChatGPTSearch beehiiv's documentation for support articles, blog posts, glossary terms, and runbooks
search_mentions
ChatGPTSearch posts, segments and automations by name for @beehiiv mentions.
update_asset
ChatGPTUpdate the metadata of an existing asset in a publication's media library. At least one editable field is required.
update_automation_step
ChatGPTUpdate a single step on an existing automation's flow. Works on live (published) automations: the change is applied to a staging workspace (a draft copy) and only affects the live automation once you publish. Pass the live or staging automation_step_id to edit. Live IDs are mapped to their staging copy. Only include the fields you want to change. Call get_automation_schema for per-step-type param shapes. When the response reports the automation live with unpublished changes, relay its publish_instructions.
add_automation_step
Claudeadd_segment_to_newsletter_list
Claudedelete_automation_step
Claudedelete_automation_trigger
Claudedelete_podcast_episode
Claudedelete_podcast_show
Claudediscover_publications
Claudeduplicate_post
Claudeduplicate_post_template
Claudeduplicate_product
Claudeedit_automation_email_content
Claudeedit_page
Claudeedit_post
Claudeedit_post_content
Claudeedit_post_template
Claudeedit_post_template_content
Claudegenerate_image
Claudeget_ad_report
Claudeget_asset
Claudeget_author
Claudeget_automation
Claudeget_automation_email_content
Claudeget_automation_journey
Claudeget_automation_schema
Claudeget_automation_stats
Claudeget_automation_workspace_diff
Claudeget_condition_set
Claudeget_condition_set_schema
Claudeget_crawler_analytics
Claudeget_current_user
Claudeget_earnings
Claudeget_engagements
Claudeget_image_generation_status
Claudeget_newsletter_list
Claudeget_order
Claudeget_page
Claudeget_podcast_episode
Claudeget_podcast_episode_stats
Claudeget_podcast_episode_transcript
Claudeget_podcast_show
Claudeget_podcast_show_stats
Claudeget_poll
Claudeget_post
Claudeget_post_content
Claudeget_post_isp_breakdown
Claudeget_post_stats
Claudeget_post_stats_batch
Claudeget_post_template_content
Claudeget_premium_offer
Claudeget_product
Claudeget_product_review_settings
Claudeget_publication
Claudeget_publication_settings
Claudeget_publication_stats
Claudeget_recommendation_partner_insights
Claudeget_referral_program
Claudeget_segment
Claudeget_segment_schema
Claudeget_subscribe_form
Claudeget_subscribe_form_diff
Claudeget_subscriber_history
Claudeget_subscription
Claudeget_subscription_batch
Claudeget_survey
Claudeget_tier
Claudeget_website_analytics
Claudeget_website_analytics_breakdown
Claudeget_website_analytics_conditions_schema
Claudeget_workspace
Claudelearn_page_metadata
Claudelearn_post_authoring
Claudelearn_post_metadata
Claudelearn_subscribe_form_authoring
Claudelist_ad_offers
Claudelist_ad_opportunities
Claudelist_ad_reports
Claudelist_assets
Claudelist_authors
Claudelist_automation_emails
Claudelist_automation_journeys
Claudelist_automations
Claudelist_condition_sets
Claudelist_content_tags
Claudelist_custom_fields
Claudelist_newsletter_list_subscriptions
Claudelist_newsletter_lists
Claudelist_orders
Claudelist_pages
Claudelist_paywalls
Claudelist_podcast_categories
Claudelist_podcast_episodes
Claudelist_podcast_shows
Claudelist_poll_responses
Claudelist_polls
Claudelist_post_click_subscribers
Claudelist_post_clicks
Claudelist_post_subscriber_engagement
Claudelist_post_templates
Claudelist_posts
Claudelist_premium_offers
Claudelist_product_coupons
Claudelist_product_promotion_codes
Claudelist_product_reviews
Claudelist_product_tags
Claudelist_products
Claudelist_publication_tags
Claudelist_publications
Claudelist_recommendation_suggestions
Claudelist_recommendations
Claudelist_referral_rewards
Claudelist_segments
Claudelist_signup_flows
Claudelist_site_redirects
Claudelist_subscribe_forms
Claudelist_subscriptions
Claudelist_survey_responses
Claudelist_surveys
Claudelist_tags
Claudelist_tiers
Clauderead_documentation
Clauderecalculate_segment
Claudereorder_automation_steps
Claudesave_audio
Claudesave_automation
Claudesave_automation_email
Claudesave_automation_trigger
Claudesave_condition_set
Claudesave_content_tag
Claudesave_current_user
Claudesave_custom_field
Claudesave_file
Claudesave_guest_author
Claudesave_image
Claudesave_newsletter_list
Claudesave_newsletter_list_preference
Claudesave_podcast_episode
Claudesave_podcast_show
Claudesave_poll
Claudesave_post
Claudesave_post_template
Claudesave_post_template_theme
Claudesave_post_theme
Claudesave_product
Claudesave_publication_settings
Claudesave_recommendation
Claudesave_referral_milestone
Claudesave_referral_program
Claudesave_referral_reward
Claudesave_segment
Claudesave_signup_flow
Claudesave_site_redirect
Claudesave_split_test
Claudesave_subscribe_form
Claudesave_subscribe_form_theme
Claudesave_subscriber_tag
Claudesave_survey
Claudesave_survey_question
Claudesave_tier
Claudesearch_cashtags
Claudesearch_documentation
Claudeupdate_asset
Claudeupdate_automation_step
Claude
