Posts
Create, read, update, delete, and publish posts.
Posts are the articles you write and send to your audience. A post starts as a draft and becomes visible on your publication — and is emailed to subscribers — when you publish it.
The post object
{
"object": "post",
"id": "post_abc123",
"title": "Hello, world",
"subtitle": "Our very first issue",
"slug": "hello-world",
"status": "published",
"content": [
{ "type": "p", "children": [{ "text": "Welcome to the newsletter." }] }
],
"cover_image_url": "https://palmframe.com/covers/hello-world.png",
"url": "https://weekly-frame.palmframe.com/hello-world",
"published_at": "2026-07-14T09:30:00.000Z",
"created_at": "2026-07-13T18:00:00.000Z",
"updated_at": "2026-07-14T09:30:00.000Z"
}| Field | Type | Description |
|---|---|---|
object | string | Always "post". |
id | string | Unique identifier. |
title | string | The post title. |
subtitle | string | null | Optional subtitle. |
slug | string | URL slug, derived from the title on creation. Immutable. |
status | string | "draft" or "published". |
content | array | The body as an array of Plate nodes. |
cover_image_url | string | null | Auto-derived from the first image in content (see below). Read-only. |
url | string | null | Public URL. null until the post is published. |
published_at | string | null | ISO 8601 timestamp of first publish, or null for drafts. |
created_at | string | ISO 8601 creation timestamp. |
updated_at | string | ISO 8601 timestamp of the last update. |
Images and the cover
Embed an image by adding an img node to content:
{ "type": "img", "url": "https://…/photo.jpg", "alt": "A caption", "children": [{ "text": "" }] }The first image in a post's body automatically becomes its
cover_image_url — used as the social thumbnail (Open Graph / Twitter card) and
in the publication's post list, Substack-style. You don't set cover_image_url
directly; it is recomputed from content on every create and update.
List posts
GET /posts| Query parameter | Type | Description |
|---|---|---|
status | string | Filter by draft or published. Omit to return all posts. |
limit | integer | Page size, 1–100. Defaults to 25. |
cursor | string | Pagination cursor. See Pagination. |
curl "https://palmframe.com/api/v1/posts?status=published&limit=25" \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"{
"object": "list",
"data": [
{
"object": "post",
"id": "post_abc123",
"title": "Hello, world",
"slug": "hello-world",
"status": "published"
}
],
"pagination": {
"limit": 25,
"has_more": false,
"next_cursor": null
}
}Create a post
POST /posts| Body field | Type | Description |
|---|---|---|
title | string | Required. The post title. The slug is derived from it. |
subtitle | string | Optional subtitle. |
content | array | Optional body as an array of Plate nodes. |
status | string | "draft" or "published". Defaults to "draft". |
curl -X POST https://palmframe.com/api/v1/posts \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
-H "Content-Type: application/json" \
-d '{
"title": "Hello, world",
"subtitle": "Our very first issue",
"content": [
{ "type": "p", "children": [{ "text": "Welcome to the newsletter." }] }
]
}'Returns 201 Created with the new post:
{
"object": "post",
"id": "post_abc123",
"title": "Hello, world",
"subtitle": "Our very first issue",
"slug": "hello-world",
"status": "draft",
"content": [
{ "type": "p", "children": [{ "text": "Welcome to the newsletter." }] }
],
"cover_image_url": null,
"url": null,
"published_at": null,
"created_at": "2026-07-13T18:00:00.000Z",
"updated_at": "2026-07-13T18:00:00.000Z"
}Retrieve a post
GET /posts/{id}curl https://palmframe.com/api/v1/posts/post_abc123 \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"Returns the post object, or
404 not_found if no post has that id.
Update a post
PATCH /posts/{id}Send only the fields you want to change. The slug is immutable and cannot
be updated.
| Body field | Type | Description |
|---|---|---|
title | string | New title. |
subtitle | string | New subtitle. |
content | array | Replacement body (array of Plate nodes). |
status | string | "draft" or "published". |
curl -X PATCH https://palmframe.com/api/v1/posts/post_abc123 \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
-H "Content-Type: application/json" \
-d '{ "subtitle": "Now with a better subtitle" }'Returns the updated post object.
Delete a post
DELETE /posts/{id}curl -X DELETE https://palmframe.com/api/v1/posts/post_abc123 \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6"Returns 200 OK:
{
"object": "post",
"id": "post_abc123",
"deleted": true
}Publish a post
POST /posts/{id}/publishPublishes the post and, on first publish, emails your subscribed readers.
| Body field | Type | Description |
|---|---|---|
email | boolean | Whether to email subscribers on first publish. Defaults to true. |
This endpoint is idempotent: re-publishing an already-published post never
re-sends the email. If you publish with email: false, no email is ever sent
for that post, even on a later re-publish.
curl -X POST https://palmframe.com/api/v1/posts/post_abc123/publish \
-H "Authorization: Bearer pf_live_a1b2c3d4e5f6g7h8i9j0k1l2m3n4o5p6" \
-H "Content-Type: application/json" \
-d '{ "email": true }'The response is the published post plus an email summary describing the send:
{
"object": "post",
"id": "post_abc123",
"title": "Hello, world",
"slug": "hello-world",
"status": "published",
"url": "https://weekly-frame.palmframe.com/hello-world",
"published_at": "2026-07-14T09:30:00.000Z",
"email": {
"attempted": 1240,
"sent": 1236,
"skipped": 4,
"error": null
}
}email field | Type | Description |
|---|---|---|
attempted | integer | Number of subscribed readers the send targeted. |
sent | integer | Number of emails successfully handed off for delivery. |
skipped | integer | Recipients skipped (e.g. unsubscribed or invalid addresses). |
error | string | null | An error message if the send failed, otherwise null. |
Publishing is idempotent
Calling publish again on a published post returns the post with an email
summary of { "attempted": 0, "sent": 0, "skipped": 0 } — the newsletter is
never sent twice.