v52

latestOpenAPI 3.1.0MITraw.githubusercontent.com2026-07-21450373.3 KB

posts

Update a post by ID

Update an existing post in your publication. The publication is identified by the API key provided in the Authorization header.

Behavior:

Only provided fields are updated; omitted fields remain unchanged
When markdown is provided, it replaces the full content. Rich blocks (embeds, buttons, callouts) created in the editor will be lost — the markdown to editor conversion is lossy for blocks without a markdown equivalent
Set status to "published" to publish a draft, "draft" to unpublish, or "archived" to archive
When editing an already-live post that should remain live, include status: "published" in the update and verify the returned post status before telling the writer it is live
Set scheduledAt (Unix timestamp in milliseconds) to schedule a draft's first-publish for a future time. Must be in the future and at most 30 days out. Only valid for posts that haven't been published or already scheduled. Pass scheduledAt: null to cancel a previously scheduled publish (or to reschedule: cancel first, then schedule again with the new time). Set sendNewsletter: true alongside scheduledAt to email subscribers when the post publishes.
Set imageUrl to update the post's cover/hero image; the URL is fetched, re-hosted, and a placeholder is generated. Pass clearImage: true to remove the existing cover.

put/v1/posts/{postId}

Path parameters

postIdstring required

Unique identifier of the post to update

Request body

markdownstring

Post content in Markdown format. Replaces the FULL body. Markdown cannot represent buttons, linked images, or embedded media (videos, tweets, link cards) — replacing a post that has any of those with markdown drops them. Use bodyJson (round-tripped from get-post) to edit an existing post so nothing is lost. Provide markdown OR bodyJson, not both.

bodyJsonstring

Post content as a Tiptap document, JSON-stringified (e.g. '{"type":"doc","content":[...]}'). This accepts ANY Tiptap node the editor supports — including videos, tweets, link cards, callouts, and buttons — so editing a post by round-tripping the json returned by get-post preserves everything markdown would drop. Replaces the FULL body; node-type validity is checked by the renderer and an unusable document is rejected. Provide markdown OR bodyJson, not both.

titlestring

Title of the post

subtitlestring

Optional subtitle or brief summary

slugstring

URL-friendly identifier for the post

postPreviewstring

Preview text for the post

authorIdsstring[]

User ids credited as the post's authors, in byline order. Replaces the full list, so include every author you want kept — read the post's current authorIds first and start from those. Each id must be the publication's owner or an active team member; ids from outside the publication are rejected. There is no endpoint that enumerates members, so an id has to come from a post you have read (authorIds on a single post, or authors[].id on a list) or from the writer.

status'draft' | 'published' | 'archived'

Set to 'published' to publish a draft or keep an already-live post published after edits, 'draft' to unpublish, or 'archived' to archive

scheduledAtinteger nullable

Unix timestamp (milliseconds) to schedule the post's first publish at a future time. Must be in the future and at most 30 days out. Only valid for draft posts that haven't been published or already scheduled. Cannot be combined with status: 'draft' or 'archived'. Pass null to cancel a previously scheduled publish. The value 0 is treated the same as omitting the field (no scheduling request); note that on an already-scheduled post, omitting scheduledAt while changing status cancels the schedule.

publishedAtinteger

Unix timestamp (milliseconds) to set as the post's publish date. Once set, the date is preserved across re-publishes.

imageUrlstring uri

URL of an image to set as the post's cover/hero image. The image is fetched, re-hosted on Paragraph's CDN, and a placeholder is generated. Pass clearImage: true instead to remove the existing cover.

clearImageboolean

When true, removes the post's existing cover/hero image. Ignored if imageUrl is also provided.

Response

Post updated successfully

successtrue required

Whether the update succeeded