beehiiv Developer Documentation

Retrieve all posts belonging to a specific publication

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Path Parameters

publicationIdstringRequiredformat: "^(pub_[0-9a-fA-F\-]+)$"

The prefixed ID of the publication object

Query Parameters

expandlist of enumsOptional

Optionally expand the results by adding additional information.
stats - Adds statistics about the post(s).
free_web_content - Adds the web HTML rendered to a free reader.
free_email_content - Adds the email HTML rendered to a free reader.
free_rss_content - Adds the RSS feed HTML.
premium_web_content - Adds the web HTML rendered to a premium reader.
premium_email_content - Adds the email HTML rendered to a premium reader.

Optionally expand the results by adding additional information. `stats` - Adds statistics about the post(s). `free_web_content` - Adds the web HTML rendered to a free reader. `free_email_content` - Adds the email HTML rendered to a free reader. `free_rss_content` - Adds the RSS feed HTML. `premium_web_content` - Adds the web HTML rendered to a premium reader. `premium_email_content` - Adds the email HTML rendered to a premium reader.

audienceenumOptionalDefaults to all

Optionally filter the results by audience

Allowed values:

platformenumOptionalDefaults to all

Optionally filter the results by platform.
web - Posts only published to web.
email - Posts only published to email.
both - Posts published to email and web.
all - Does not restrict results by platform.

Allowed values:

statusenumOptionalDefaults to all

Optionally filter the results by the status of the post.
draft - not been scheduled.
confirmed - The post will be active after the scheduled_at.
archived - The post is no longer active.
all - Does not restrict results by status.

Allowed values:

content_tags[]list of stringsOptional

Optionally filter posts by content_tags. Adding a content tag will return any post with that content tag associated to it.

Example: Filtering for content_tags: ["sales","closing"] will return results of posts that have either sales or closing content_tags.

slugs[]list of stringsOptional

Optionally filter posts by their slugs. Adding a slug will return any post with that exact slug associated to it.

Example: Filtering for slugs: ["my-first-post","another-post"] will return results of posts that have either my-first-post or another-post as their slug.

premium_tierslist of stringsOptional

Optionally filter posts by audience based on premium tiers.
This takes in an array of Display Names of the premium tiers.
It will also scope any expanded content output to the specified premium tiers.
Note: This is case insensitive.

limitintegerOptional

A limit on the number of objects to be returned. The limit can range between 1 and 100, and the default is 10.

pageintegerOptional

Pagination returns the results in pages. Each page contains the number of results specified by the limit (default: 10).
If not specified, results 1-10 from page 1 will be returned.

order_byenumOptionalDefaults to created

The field that the results are sorted by. Defaults to created
created - The time in which the post was first created.
publish_date - The time the post was set to be published.
displayed_date - The time displayed in place of the publish_date. If no displayed_date was set, it will default to the publish_date

The field that the results are sorted by. Defaults to created `created` - The time in which the post was first created. `publish_date` - The time the post was set to be published. `displayed_date` - The time displayed in place of the `publish_date`. If no `displayed_date` was set, it will default to the `publish_date`

Allowed values:

directionenumOptionalDefaults to asc

The direction that the results are sorted in. Defaults to asc
asc - Ascending, sorts from smallest to largest.
desc - Descending, sorts from largest to smallest.

Allowed values:

hidden_from_feedenumOptionalDefaults to all

Optionally filter the results by the hidden_from_feed attribute of the post.
all - Does not restrict results by hidden_from_feed.
true - Only return posts hidden from the feed.
false - Only return posts that are visible on the feed.

Allowed values:

Response

datalist of objects

limitinteger

The limit placed on the results. If no limit was specified in the request,this defaults to 10.

pageinteger>=0Defaults to 1

The page number the results are from. If no page was specified in the request, this defaults to page 1.

total_resultsinteger

The total number of results from all pages.

total_pagesinteger

The total number of pages.

1	import requests
2
3	url = "https://api.beehiiv.com/v2/publications/pub_00000000-0000-0000-0000-000000000000/posts"
4
5	headers = {"Authorization": "Bearer <token>"}
6
7	response = requests.get(url, headers=headers)
8
9	print(response.json())

1	{
2	"data": [
3	{
4	"id": "post_00000000-0000-0000-0000-000000000000",
5	"subtitle": "New post subtitle",
6	"title": "New Post Title",
7	"authors": [
8	"Clark Kent"
9	],
10	"created": 1666800076,
11	"status": "draft",
12	"split_tested": true,
13	"subject_line": "Check this out",
14	"preview_text": "More news on the horizon",
15	"slug": "slug",
16	"thumbnail_url": "thumbnail_url",
17	"web_url": "web_url",
18	"audience": "free",
19	"platform": "web",
20	"content_tags": [
21	"content_tags"
22	],
23	"hidden_from_feed": true,
24	"publish_date": 1666800076,
25	"displayed_date": 1666800076,
26	"meta_default_description": "A post with great content",
27	"meta_default_title": "My great post",
28	"content": {
29	"free": {
30	"web": "<HTML><body><h1>New Post</h1></body></HTML>",
31	"email": "<HTML><body><h1>New Post</h1></body></HTML>",
32	"rss": "<HTML><body><h1>New Post</h1></body></HTML>"
33	},
34	"premium": {
35	"web": "<HTML><body><h1>New Post</h1></body></HTML>",
36	"email": "<HTML><body><h1>New Post</h1></body></HTML>"
37	}
38	},
39	"stats": {
40	"email": {
41	"recipients": 100,
42	"delivered": 100,
43	"opens": 50,
44	"unique_opens": 45,
45	"open_rate": 45,
46	"clicks": 10,
47	"unique_clicks": 8,
48	"click_rate": 8,
49	"unsubscribes": 1,
50	"spam_reports": 1
51	},
52	"web": {
53	"views": 200,
54	"clicks": 40
55	},
56	"clicks": [
57	{
58	"url": "https://www.google.com",
59	"email": {
60	"clicks": 10,
61	"unique_clicks": 8,
62	"click_through_rate": 80
63	},
64	"web": {
65	"clicks": 40,
66	"unique_clicks": 40,
67	"click_through_rate": 20
68	},
69	"total_clicks": 50,
70	"total_unique_clicks": 48,
71	"total_click_through_rate": 40
72	}
73	]
74	}
75	}
76	],
77	"limit": 1,
78	"page": 1,
79	"total_results": 1,
80	"total_pages": 1
81	}

List posts

Authentication

Path Parameters

Query Parameters

Response

Errors