A reference guide for building AI agents: every method, how to authenticate, and the permissions each one needs.
The beehiiv API is how an app or AI agent works with a beehiiv publication: adding a subscriber, reading a newsletter post, building an audience segment, or enrolling someone into an automation. Access is granted through an API key sent as a Bearer token, or an OAuth token whose scopes set which areas a call can read or write, and either is tied to one organization and its publications. beehiiv treats its major version as a long-lived contract and can push events to a registered endpoint when activity happens.
How an app or AI agent connects to beehiiv determines what it can reach. There is a route for making calls, a route for receiving events, and a hosted server that exposes beehiiv tools to agents, and each is governed by the key or token behind it and the publication it is tied to.
The REST API takes JSON request bodies, returns JSON, and pages through lists with page and limit parameters, at https://api.beehiiv.com/v2. Most calls name a single publication by its id in the path. A call authenticates with a Bearer token in the Authorization header, either an API key or an OAuth access token.
beehiiv POSTs an event to an HTTPS endpoint registered on a publication when something happens, like subscription.created or post.sent. Endpoints are created and managed through the webhooks methods, and an integration subscribes to the event types it cares about so it reacts to activity without polling.
A first-party Model Context Protocol server connects a beehiiv account to AI clients like Claude and ChatGPT. It launched in March 2026 with read-only access, covering content, subscribers, analytics, automations, and more, with write actions on paid plans. It is connected and managed from beehiiv workspace settings rather than by holding a raw API key in the agent.
An API key is created in beehiiv workspace settings and sent as a Bearer token in the Authorization header. It carries full access to the organization it belongs to and has no per-endpoint scopes, so it can call every area on every publication in that organization. It must be kept secret and never exposed in client code.
For an integration built for other people, beehiiv recommends OAuth instead of an API key. The resulting access token is sent as a Bearer token and carries scopes, named area:read or area:write such as subscriptions:write or posts:read, that limit which areas the token can reach. This is the granular permission model the per-method scopes in this reference describe.
The beehiiv API is split into areas an agent can act on, like a publication's posts, its subscriptions, segments, custom fields, automations, and paid tiers. Each area has its own methods, and writes in some areas add or remove real subscribers and publish real newsletters.
Methods for listing and reading the publications a token can reach.
Methods for working with newsletter posts and their stats.
Methods for working with a publication's subscribers.
Methods for building and reading audience segments.
Methods for the custom fields stored on subscribers.
Methods for reading automations and enrolling subscribers.
Methods for the publication's paid subscription tiers.
Methods for reading the publication's referral program.
Methods for registering and managing event endpoints.
Filter by method, access, or permission, or search any path. Select a row for version detail, rate limits, the related webhook event, and the source.
| Method | Endpoint | What it does | Access | Permission | Version | |
|---|---|---|---|---|---|---|
PublicationsMethods for listing and reading the publications a token can reach.2 | ||||||
| GET | /v2/publications | List the publications the token can reach. | read | publications:read | Current | |
Read-only. A raw API key reaches every publication in its organization. Acts onpublication Permission (capability) publications:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId} | Get a single publication by id, optionally expanding subscriber counts and stats. | read | publications:read | Current | |
Read-only. Acts onpublication Permission (capability) publications:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
PostsMethods for working with newsletter posts and their stats.5 | ||||||
| GET | /v2/publications/{publicationId}/posts | List the posts in a publication. | read | posts:read | Current | |
Read-only. Acts onpost Permission (capability) posts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId}/posts/{postId} | Get a single post by id, including its content and stats. | read | posts:read | Current | |
Read-only. Acts onpost Permission (capability) posts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId}/posts/aggregate_stats | Get combined statistics across the posts in a publication. | read | posts:read | Current | |
Read-only; supports filtering by audience, platform, status, and author. Acts onpost Permission (capability) posts:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/publications/{publicationId}/posts | Create a post, the email blast or newsletter sent to a publication's audience. | write | posts:write | Current | |
Builds the email from content blocks; can send or schedule the newsletter. Acts onpost Permission (capability) posts:writeVersionAvailable since the API’s base version Webhook event post.sentRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/publications/{publicationId}/posts/{postId} | Delete or archive a post; confirmed posts are archived, drafts are removed. | write | posts:write | Current | |
A confirmed post becomes archived; a draft is permanently deleted. Acts onpost Permission (capability) posts:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SubscriptionsMethods for working with a publication's subscribers.8 | ||||||
| GET | /v2/publications/{publicationId}/subscriptions | List the subscriptions belonging to a publication. | read | subscriptions:read | Current | |
Read-only; returns subscriber records page by page. Acts onsubscription Permission (capability) subscriptions:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId}/subscriptions/{subscriptionId} | Get a single subscription by its id. | read | subscriptions:read | Current | |
Read-only. Acts onsubscription Permission (capability) subscriptions:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId}/subscriptions/by_email/{email} | Get a subscription by the subscriber's email address. | read | subscriptions:read | Current | |
Read-only; the email lookup returns the subscriber record. Acts onsubscription Permission (capability) subscriptions:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/publications/{publicationId}/subscriptions | Create a subscription on a publication from an email address. | write | subscriptions:write | Current | |
email is required; can reactivate a previously unsubscribed address. Acts onsubscription Permission (capability) subscriptions:writeVersionAvailable since the API’s base version Webhook event subscription.createdRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/publications/{publicationId}/subscriptions/{subscriptionId} | Update a subscription by its id, like its tier or custom field values. | write | subscriptions:write | Current | |
A core write to a real subscriber. Acts onsubscription Permission (capability) subscriptions:writeVersionAvailable since the API’s base version Webhook event subscription.upgradedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| PUT | /v2/publications/{publicationId}/subscriptions/by_email/{email} | Update a subscription identified by the subscriber's email address. | write | subscriptions:write | Current | |
Same write as the id form, keyed on email. Acts onsubscription Permission (capability) subscriptions:writeVersionAvailable since the API’s base version Webhook event subscription.upgradedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/publications/{publicationId}/subscriptions/{subscriptionId} | Delete a subscription from a publication. | write | subscriptions:write | Current | |
Removes the subscriber from the publication. Acts onsubscription Permission (capability) subscriptions:writeVersionAvailable since the API’s base version Webhook event subscription.deletedRate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/publications/{publicationId}/subscriptions/{subscriptionId}/tags | Add a tag to a subscription. | write | subscriptions:write | Current | |
Tags a real subscriber for later segmentation. Acts onsubscription_tag Permission (capability) subscriptions:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
SegmentsMethods for building and reading audience segments.6 | ||||||
| GET | /v2/publications/{publicationId}/segments | List the audience segments in a publication. | read | segments:read | Current | |
Read-only. Acts onsegment Permission (capability) segments:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId}/segments/{segmentId} | Get a single segment by id. | read | segments:read | Current | |
Read-only. Acts onsegment Permission (capability) segments:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId}/segments/{segmentId}/members | List the subscribers in a segment with their full detail. | read | segments:read | Current | |
Read-only; returns email addresses and custom fields. Acts onsegment_member Permission (capability) segments:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId}/segments/{segmentId}/results | List only the subscription ids in a segment, for counting or external lookups. | read | segments:read | Current | |
Read-only; a lightweight array of ids without subscriber detail. Acts onsegment_member Permission (capability) segments:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/publications/{publicationId}/segments | Create a dynamic or manual segment for a publication's audience. | write | segments:write | Current | |
A dynamic segment built on custom field filters updates as values change. Acts onsegment Permission (capability) segments:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/publications/{publicationId}/segments/{segmentId} | Delete a segment from a publication. | write | segments:write | Current | |
Removes the segment; it does not delete the subscribers in it. Acts onsegment Permission (capability) segments:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Custom FieldsMethods for the custom fields stored on subscribers.4 | ||||||
| GET | /v2/publications/{publicationId}/custom_fields | List the custom fields defined on a publication's subscribers. | read | custom_fields:read | Current | |
Read-only. Acts oncustom_field Permission (capability) custom_fields:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId}/custom_fields/{id} | Get a single custom field by id. | read | custom_fields:read | Current | |
Read-only. Acts oncustom_field Permission (capability) custom_fields:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/publications/{publicationId}/custom_fields | Create a custom field on a publication's subscribers. | write | custom_fields:write | Current | |
Adds a field to the publication's subscriber schema. Acts oncustom_field Permission (capability) custom_fields:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/publications/{publicationId}/custom_fields/{id} | Delete a custom field from a publication. | write | custom_fields:write | Current | |
Removes the field and its stored values from subscribers. Acts oncustom_field Permission (capability) custom_fields:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
AutomationsMethods for reading automations and enrolling subscribers.3 | ||||||
| GET | /v2/publications/{publicationId}/automations | List the automations configured on a publication. | read | automations:read | Current | |
Read-only. Acts onautomation Permission (capability) automations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId}/automations/{automationId} | Get a single automation by id. | read | automations:read | Current | |
Read-only. Acts onautomation Permission (capability) automations:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/publications/{publicationId}/automations/{automationId}/journeys | Enroll an existing subscriber into an automation flow. | write | automations:write | Current | |
Requires the automation to have an active Add by API trigger. Acts onautomation_journey Permission (capability) automations:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
TiersMethods for the publication's paid subscription tiers.3 | ||||||
| GET | /v2/publications/{publicationId}/tiers | List the paid subscription tiers in a publication. | read | tiers:read | Current | |
Read-only. Acts ontier Permission (capability) tiers:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| GET | /v2/publications/{publicationId}/tiers/{tierId} | Get a single paid tier by id. | read | tiers:read | Current | |
Read-only. Acts ontier Permission (capability) tiers:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/publications/{publicationId}/tiers | Create a paid subscription tier for a publication. | write | tiers:write | Current | |
Defines a paid offering subscribers can be placed on. Acts ontier Permission (capability) tiers:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
Referral ProgramMethods for reading the publication's referral program.1 | ||||||
| GET | /v2/publications/{publicationId}/referral_program | Get the referral program configured on a publication. | read | referral_program:read | Current | |
Read-only. Acts onreferral_program Permission (capability) referral_program:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
WebhooksMethods for registering and managing event endpoints.3 | ||||||
| GET | /v2/publications/{publicationId}/webhooks | List the webhook endpoints registered on a publication. | read | webhooks:read | Current | |
Read-only. Acts onwebhook Permission (capability) webhooks:readVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| POST | /v2/publications/{publicationId}/webhooks | Register a webhook endpoint and the event types it should receive. | write | webhooks:write | Current | |
Subscribes the endpoint to events like subscription.created and post.sent. Acts onwebhook Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
| DELETE | /v2/publications/{publicationId}/webhooks/{endpointId} | Delete a webhook endpoint so it stops receiving events. | write | webhooks:write | Current | |
Stops event delivery to that endpoint. Acts onwebhook Permission (capability) webhooks:writeVersionAvailable since the API’s base version Webhook eventNone Rate limitStandard limits apply SourceOfficial documentation ↗ | ||||||
beehiiv can notify an app when something happens in a publication, like a new subscriber confirming or a post being sent. It POSTs an event to a registered endpoint, so an integration learns about activity without polling.
| Event | What it signals | Triggered by |
|---|---|---|
subscription.created | A new subscription was created on the publication, for example because an agent added a subscriber. | /v2/publications/{publicationId}/subscriptions |
subscription.confirmed | A subscriber confirmed their subscription, for example by completing double opt-in. | /v2/publications/{publicationId}/subscriptions |
subscription.deleted | A subscription was deleted or unsubscribed from the publication. | /v2/publications/{publicationId}/subscriptions/{subscriptionId} |
subscription.upgraded | A subscription moved up to a paid tier. | /v2/publications/{publicationId}/subscriptions/{subscriptionId}/v2/publications/{publicationId}/subscriptions/by_email/{email} |
post.sent | A post was sent to the audience as an email newsletter. | /v2/publications/{publicationId}/posts |
post.scheduled | A post was scheduled to be sent at a future time. | /v2/publications/{publicationId}/posts |
beehiiv limits how fast an app can call, by a request rate measured per minute and counted across the whole organization rather than per key.
beehiiv allows 180 requests per minute, counted across the whole organization rather than per API key, so several agents or keys sharing one organization draw down the same budget. Every response carries RateLimit-Limit, RateLimit-Remaining, and RateLimit-Reset headers showing the ceiling, what is left, and when the window resets as a Unix timestamp. Going over returns HTTP 429, and beehiiv recommends retrying with exponential backoff.
List endpoints page through results with page and limit query parameters and return total_results and total_pages alongside the data, so an integration walks pages until it has them all. The segment results endpoint returns subscription ids only, for counting or external lookups, while the members endpoint returns full subscriber detail.
A list endpoint returns a bounded page of records set by the limit parameter rather than the whole collection at once. Post and segment payloads are built from typed fields and content blocks rather than free-form size limits, and large audiences are read page by page.
The status codes an agent should handle, and what to do about each.
| Status | Code | Meaning | What to do |
|---|---|---|---|
| 400 | bad_request | The request was malformed or carried invalid data, like a missing required field or a bad parameter. | Read the message in the errors array, fix the request body or parameters, and resend. The request is not retryable as-is. |
| 401 | unauthorized | No valid Bearer token was provided, or the token is wrong or revoked. | Confirm a valid API key or OAuth token is sent in the Authorization header, and rotate the key if it may be compromised. |
| 404 | not_found | The publication, subscription, or other object does not exist, or is not visible to this token. | Verify the publication id and object id, and confirm the token belongs to the organization that owns them. |
| 429 | too_many_requests | The organization went over 180 requests per minute. The RateLimit-Reset header gives the Unix time the window resets. | Back off and retry with exponential backoff, and smooth the request rate across the organization's keys. |
| 500 | internal_server_error | An error on beehiiv's side. It is rare. | Retry with backoff, and contact beehiiv support if it persists. |
beehiiv pins a single major version of its API in the path and treats it as a long-lived contract, promising no breaking changes or deprecations without advance notice.
beehiiv's current major version, launched in December 2022 and carried in the request path. beehiiv treats v2 as a long-lived contract and states it will not introduce breaking changes or deprecations without advance notice, so new fields and methods are added over time without breaking existing calls.
beehiiv released v1 of its official Model Context Protocol server, connecting a beehiiv account to AI clients like Claude and ChatGPT. It started with read-only access, letting an agent query subscribers, posts, and analytics without making changes; write actions arrived on paid plans.
beehiiv added the ability to create and send posts through the API, bringing newsletter sending into existing content workflows rather than only the beehiiv editor.
beehiiv introduced webhooks, letting an integration register an endpoint and receive events when subscriptions and posts change, instead of polling the list endpoints.
Build against v2 and expect new fields to be added without breaking existing calls.
beehiiv API product updates ↗Bollard AI sits between a team's AI agents and beehiiv. Grant each agent exactly the access it needs, read or write, area by area, and every call is checked and logged.