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.
Set imageAlt to describe the cover image for screen readers. It renders everywhere the cover appears, so set it whenever you set imageUrl.

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.

canonicalUrlstring uri nullable

Canonical URL used in rendered metadata. Pass null to clear it. This does not change the post's Paragraph permalink.

publishOnlineboolean

Whether the post should be publicly visible online when published. Set false for newsletter-only delivery.

communityIdstring nullable

Subscriber segment id for newsletter delivery. Pass null for the general audience. Unavailable or cross-publication segments are rejected rather than broadened.

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.

imageAltstring nullable

Alternative text describing the cover image. Set it alongside imageUrl when replacing the image; on its own it re-describes the existing cover. Pass null or an empty string to clear it. Ignored when the post has no cover.

Response

Post updated successfully

successtrue required

Whether the update succeeded

Changes

Changed in 10 of the 61 revisions of this API.413

Aug 28, 20268108f2a53d2e3See the full diff
- ○
  added the new optional request property canonicalUrl
  new-optional-request-property
- ○
  added the new optional request property communityId
  new-optional-request-property
- ○
  added the new optional request property publishOnline
  new-optional-request-property
Aug 25, 2026a38cc07e90d81See the full diff
- ○
  added the new optional request property imageAlt
  new-optional-request-property
Jul 21, 2026644a3e39740b1See the full diff
- ○
  added the new optional request property authorIds
  new-optional-request-property
Jun 25, 202617b3077bd1191See the full diff
- ○
  added the new optional request property bodyJson
  new-optional-request-property
Jun 22, 20269c830051404c1See the full diff
- ○
  added the non-success response with the status 409
  response-non-success-status-added
May 8, 2026bd33b6b2bee82See the full diff
- ○
  added the new optional request property clearImage
  new-optional-request-property
- ○
  added the new optional request property imageUrl
  new-optional-request-property
May 7, 202690de04b871334See the full diff
- ●
  removed the optional property error from the response with the 400 status
  response-optional-property-removed
- ●
  removed the optional property error from the response with the 401 status
  response-optional-property-removed
- ●
  removed the optional property error from the response with the 404 status
  response-optional-property-removed
- ●
  removed the optional property error from the response with the 500 status
  response-optional-property-removed
Apr 28, 202679fe03bb40571See the full diff
- ○
  added the new optional request property publishedAt
  new-optional-request-property
Apr 14, 202683a5758697642See the full diff
- ○
  added the new optional request property scheduledAt
  new-optional-request-property
- ○
  added the new optional request property sendNewsletter
  new-optional-request-property
Mar 20, 20265b94722856861See the full diff
- ○
  endpoint added
  endpoint-added

Full history