{"openapi":"3.1.0","info":{"title":"beehiiv Public API & Agent Surface","version":"1.0.0","summary":"Machine-readable API for beehiiv marketing agent endpoints and the core publisher REST API.","description":"Use this document to discover how agents integrate with beehiiv. Marketing MCP and markdown twins live on www.beehiiv.com. Publisher CRUD (subscriptions, posts, publications) lives on api.beehiiv.com/v2 and requires an API key from the beehiiv dashboard. Full Fern-generated reference YAML: https://developers.beehiiv.com/openapi/api-reference.yaml","contact":{"name":"beehiiv Developers","url":"https://developers.beehiiv.com"},"license":{"name":"Proprietary","url":"https://www.beehiiv.com/tou"}},"externalDocs":{"description":"Human developer documentation, SDKs, and webhooks","url":"https://developers.beehiiv.com"},"servers":[{"url":"https://www.beehiiv.com","description":"Marketing site, markdown twins, MCP, and agent helpers"}],"tags":[{"name":"Agent discovery","description":"Indexes and schemas for AI agents"},{"name":"Markdown content","description":"Clean text/markdown twins of marketing pages"},{"name":"Marketing MCP","description":"Model Context Protocol tools for pricing and content"},{"name":"Support search","description":"Public knowledge-base and blog search"},{"name":"Publications","description":"beehiiv REST — publication resources"},{"name":"Subscriptions","description":"beehiiv REST — subscriber management"},{"name":"Posts","description":"beehiiv REST — newsletter posts"}],"paths":{"/openapi.json":{"get":{"operationId":"getOpenApiSpec","tags":["Agent discovery"],"summary":"Download this OpenAPI document","description":"Returns the OpenAPI 3.1 JSON document describing public beehiiv agent endpoints and core REST operations. Prefer this file for function-calling tool generation.","responses":{"200":{"description":"OpenAPI 3.1 document","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}}}}}}},"/llms.txt":{"get":{"operationId":"getLlmsTxt","tags":["Agent discovery"],"summary":"Curated agent index (llms.txt)","description":"Returns the curated markdown index of beehiiv pages, when-to-use guidance, MCP tips, and CLI pointers.","responses":{"200":{"description":"llms.txt body","content":{"text/plain":{"schema":{"type":"string"}}}}}}},"/api/markdown/{path}":{"get":{"operationId":"getPageMarkdown","tags":["Markdown content"],"summary":"Fetch a marketing page as markdown","description":"Convert a live marketing HTML page into a clean markdown twin. Equivalent to requesting `/{path}.md` or sending `Accept: text/markdown` to the HTML URL. Homepage: omit path or use empty segments.","parameters":[{"name":"path","in":"path","required":true,"description":"URL path without leading slash (e.g. `pricing`, `features/automations`). Use `index` for the homepage when calling this route directly.","schema":{"type":"string"}}],"responses":{"200":{"description":"Markdown twin","content":{"text/markdown":{"schema":{"type":"string"}}}},"404":{"description":"Path not found","content":{"text/markdown":{"schema":{"type":"string"}},"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"502":{"description":"Upstream page unavailable","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/api/mcp/tools":{"get":{"operationId":"listMarketingMcpTools","tags":["Marketing MCP"],"summary":"List public marketing MCP tools (no auth)","description":"Public JSON catalog of tools exposed by the www.beehiiv.com marketing MCP server at `/api/mcp`. Product workspace MCP at https://mcp.beehiiv.com/mcp requires OAuth.","responses":{"200":{"description":"Tool catalog","content":{"application/json":{"schema":{"$ref":"#/components/schemas/McpToolCatalog"}}}}}}},"/api/mcp":{"post":{"operationId":"invokeMarketingMcp","tags":["Marketing MCP"],"summary":"Marketing MCP Streamable HTTP endpoint","description":"Model Context Protocol Streamable HTTP transport for marketing tools (`get_pricing`, `compare_with`, `get_company_facts`, `get_page_markdown`, `list_pages`, `pricing_faq`). Clients should send `Accept: application/json, text/event-stream`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":true,"description":"JSON-RPC MCP message"}}}},"responses":{"200":{"description":"MCP JSON-RPC or SSE response","content":{"application/json":{"schema":{"type":"object","additionalProperties":true}},"text/event-stream":{"schema":{"type":"string"}}}}}}},"/api/support/search":{"get":{"operationId":"searchSupportContent","tags":["Support search"],"summary":"Search help center, blog, and product updates","description":"Public search across beehiiv support articles, blog posts, and product updates from product.beehiiv.com. Returns ranked JSON hits with URLs (markdown twins available for articles/posts). Product updates are point-in-time release notes; their description starts with the publish date.","parameters":[{"name":"q","in":"query","required":true,"description":"Search query string","schema":{"type":"string","minLength":1}},{"name":"type","in":"query","required":false,"description":"Optional content type filter","schema":{"type":"string","enum":["article","blog","update"]}}],"responses":{"200":{"description":"Search results","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SupportSearchResponse"}}}},"400":{"description":"Missing or invalid query","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"500":{"description":"Search backend failure","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/publications":{"servers":[{"url":"https://api.beehiiv.com/v2","description":"Publisher REST API (API key / OAuth required)"}],"get":{"operationId":"listPublications","tags":["Publications"],"summary":"List publications for the authenticated account","description":"REST API on api.beehiiv.com/v2. Returns publications the API key can access. Authenticate with `Authorization: Bearer <api_key>`.","security":[{"bearerAuth":[]}],"responses":{"200":{"description":"Publication list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PublicationListResponse"}}}},"401":{"description":"Missing or invalid API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"default":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/publications/{publicationId}":{"servers":[{"url":"https://api.beehiiv.com/v2","description":"Publisher REST API (API key / OAuth required)"}],"get":{"operationId":"getPublication","tags":["Publications"],"summary":"Get a publication by ID","description":"Fetch a single publication (`pub_…` prefixed ID) from api.beehiiv.com/v2.","security":[{"bearerAuth":[]}],"parameters":[{"name":"publicationId","in":"path","required":true,"description":"Prefixed publication ID (e.g. pub_00000000-0000-0000-0000-000000000000)","schema":{"type":"string","pattern":"^pub_"}}],"responses":{"200":{"description":"Publication","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Publication"}}}},"404":{"description":"Not found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/publications/{publicationId}/subscriptions":{"servers":[{"url":"https://api.beehiiv.com/v2","description":"Publisher REST API (API key / OAuth required)"}],"get":{"operationId":"listSubscriptions","tags":["Subscriptions"],"summary":"List subscribers for a publication","description":"Paginated subscriber list for a publication. Filter by email, status, and expansion fields as documented on developers.beehiiv.com.","security":[{"bearerAuth":[]}],"parameters":[{"name":"publicationId","in":"path","required":true,"schema":{"type":"string","pattern":"^pub_"}},{"name":"email","in":"query","required":false,"description":"Filter by subscriber email","schema":{"type":"string","format":"email"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Subscription page","content":{"application/json":{"schema":{"$ref":"#/components/schemas/SubscriptionListResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}},"post":{"operationId":"createSubscription","tags":["Subscriptions"],"summary":"Create or upsert a subscriber","description":"Add a subscriber to a publication. Idempotent on email for the same publication when using matching upsert semantics — see developers.beehiiv.com for exact behavior.","security":[{"bearerAuth":[]}],"parameters":[{"name":"publicationId","in":"path","required":true,"schema":{"type":"string","pattern":"^pub_"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateSubscriptionRequest"}}}},"responses":{"200":{"description":"Existing subscription updated/returned","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"201":{"description":"Subscription created","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Subscription"}}}},"400":{"description":"Validation error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}},"/publications/{publicationId}/posts":{"servers":[{"url":"https://api.beehiiv.com/v2","description":"Publisher REST API (API key / OAuth required)"}],"get":{"operationId":"listPosts","tags":["Posts"],"summary":"List posts for a publication","description":"List newsletter posts (drafts and published) for a publication.","security":[{"bearerAuth":[]}],"parameters":[{"name":"publicationId","in":"path","required":true,"schema":{"type":"string","pattern":"^pub_"}},{"name":"limit","in":"query","required":false,"schema":{"type":"integer","minimum":1,"maximum":100,"default":10}},{"name":"cursor","in":"query","required":false,"schema":{"type":"string"}}],"responses":{"200":{"description":"Post list","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PostListResponse"}}}}}},"post":{"operationId":"createPost","tags":["Posts"],"summary":"Create a post","description":"Create a draft or scheduled post for a publication via the REST API. Available only to publications on the Pro and Enterprise plans. Supply content with either `blocks` or `body_content` — exactly one of the two. Creation is asynchronous: this returns 201 with a stable post ID immediately, but the post is still being built. A follow-up `getPost` may return 202 while creation is in flight (retry, honoring `Retry-After`) or 404 with code `POST_CREATION_FAILED` if it failed — stop retrying in that case. Full field reference: https://developers.beehiiv.com/openapi/api-reference.yaml","security":[{"bearerAuth":[]}],"parameters":[{"name":"publicationId","in":"path","required":true,"schema":{"type":"string","pattern":"^pub_"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreatePostRequest"}}}},"responses":{"201":{"description":"Post accepted for creation. The returned ID is stable, but the post may not be readable yet.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Post"}}}},"400":{"description":"Invalid body — commonly neither or both of `blocks` and `body_content`","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}},"403":{"description":"Publication is not on a plan that allows post creation (Pro or Enterprise)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ApiError"}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from the beehiiv dashboard (Settings → API). Send as `Authorization: Bearer <token>`. Required for api.beehiiv.com/v2 operations."}},"schemas":{"ApiError":{"type":"object","required":["error"],"properties":{"error":{"type":"object","required":["code","message"],"properties":{"code":{"type":"string","description":"Stable machine-readable error code","examples":["bad_request","not_found","unauthorized"]},"message":{"type":"string","description":"Human-readable explanation"},"resolution":{"type":"string","description":"Hint for how an agent or developer should recover"},"details":{"type":"object","additionalProperties":true}}}}},"McpToolCatalog":{"type":"object","required":["server","transport","tools"],"properties":{"server":{"type":"string","format":"uri"},"transport":{"type":"string","examples":["streamable-http"]},"tools":{"type":"array","items":{"$ref":"#/components/schemas/McpToolSummary"}}}},"McpToolSummary":{"type":"object","required":["name","description"],"properties":{"name":{"type":"string"},"title":{"type":"string"},"description":{"type":"string"},"inputSchema":{"type":"object","additionalProperties":true}}},"SupportSearchResponse":{"type":"array","description":"Ranked search hits (newest shape: bare JSON array)","items":{"type":"object","required":["id","type","title"],"properties":{"id":{"type":"string"},"type":{"type":"string","enum":["article","blog","update"]},"title":{"type":"string"},"description":{"type":["string","null"]},"url":{"type":["string","null"],"format":"uri"}}}},"Publication":{"type":"object","properties":{"id":{"type":"string","pattern":"^pub_"},"name":{"type":"string"},"organization_name":{"type":"string"}}},"PublicationListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Publication"}}}},"Subscription":{"type":"object","properties":{"id":{"type":"string"},"email":{"type":"string","format":"email"},"status":{"type":"string","enum":["validating","invalid","pending","active","inactive"]}}},"SubscriptionListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Subscription"}},"limit":{"type":"integer"},"page":{"type":"integer"},"total_results":{"type":"integer"},"total_pages":{"type":"integer"}}},"CreateSubscriptionRequest":{"type":"object","required":["email"],"properties":{"email":{"type":"string","format":"email"},"reactivate_existing":{"type":"boolean"},"send_welcome_email":{"type":"boolean"},"utm_source":{"type":"string"},"utm_medium":{"type":"string"},"utm_campaign":{"type":"string"},"referring_site":{"type":"string","format":"uri"},"custom_fields":{"type":"array","items":{"type":"object","required":["name","value"],"properties":{"name":{"type":"string"},"value":{}}}}}},"Post":{"type":"object","properties":{"id":{"type":"string","pattern":"^post_"},"title":{"type":"string"},"subtitle":{"type":"string"},"status":{"type":"string","enum":["draft","confirmed","archived"]}}},"PostListResponse":{"type":"object","properties":{"data":{"type":"array","items":{"$ref":"#/components/schemas/Post"}}}},"CreatePostRequest":{"type":"object","description":"Exactly one of `blocks` or `body_content` is required. `<style>` and `<link>` tags are stripped from HTML during sanitization — use inline styles.","oneOf":[{"required":["blocks"]},{"required":["body_content"]}],"properties":{"blocks":{"type":"array","description":"Structured content blocks (paragraph, image, heading, button, html, table, list, columns, …). Block schemas are documented in the full Fern reference.","items":{"type":"object"}},"body_content":{"type":"string","description":"Post content as a single raw HTML string, wrapped in an htmlSnippet block internally."},"title":{"type":"string"},"subtitle":{"type":"string"},"post_template_id":{"type":"string","description":"Template to render the post with. Defaults to the publication's default template."},"status":{"type":"string","enum":["draft","confirmed"],"default":"draft","description":"`confirmed` publishes immediately, or at `scheduled_at` when supplied. A draft post cannot be scheduled."},"scheduled_at":{"type":"string","format":"date-time","description":"Publish time. Requires `status: confirmed`."},"custom_link_tracking_enabled":{"type":"boolean"},"thumbnail_image_url":{"type":"string","format":"uri"}}}}}}