Palmframe API

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"
}
FieldTypeDescription
objectstringAlways "post".
idstringUnique identifier.
titlestringThe post title.
subtitlestring | nullOptional subtitle.
slugstringURL slug, derived from the title on creation. Immutable.
statusstring"draft" or "published".
contentarrayThe body as an array of Plate nodes.
cover_image_urlstring | nullAuto-derived from the first image in content (see below). Read-only.
urlstring | nullPublic URL. null until the post is published.
published_atstring | nullISO 8601 timestamp of first publish, or null for drafts.
created_atstringISO 8601 creation timestamp.
updated_atstringISO 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 parameterTypeDescription
statusstringFilter by draft or published. Omit to return all posts.
limitintegerPage size, 1–100. Defaults to 25.
cursorstringPagination 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 fieldTypeDescription
titlestringRequired. The post title. The slug is derived from it.
subtitlestringOptional subtitle.
contentarrayOptional body as an array of Plate nodes.
statusstring"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 fieldTypeDescription
titlestringNew title.
subtitlestringNew subtitle.
contentarrayReplacement body (array of Plate nodes).
statusstring"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}/publish

Publishes the post and, on first publish, emails your subscribed readers.

Body fieldTypeDescription
emailbooleanWhether 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 fieldTypeDescription
attemptedintegerNumber of subscribed readers the send targeted.
sentintegerNumber of emails successfully handed off for delivery.
skippedintegerRecipients skipped (e.g. unsubscribed or invalid addresses).
errorstring | nullAn 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.

On this page