posts

Create a new post

Create a new post in your publication. The publication is identified by the API key provided in the Authorization header.

Requirements:

title field is required
Provide content as either markdown (converted to TipTap JSON) OR bodyJson (a Tiptap document for content with buttons/linked images) — exactly one is required, not both

Behavior:

The post will be created as published by default. Set status to "draft" to create a draft instead
If sendNewsletter is true, an email will be sent to all subscribers when the post publishes
Set scheduledAt (Unix timestamp in milliseconds) to schedule first-publish for a future time. Must be in the future and at most 30 days out. Scheduling cannot be combined with status: "draft". When scheduled, the response status is "scheduled" and the post publishes (plus sends newsletter, if requested) at the scheduled time.

post/v1/posts

Request body

markdownstring

Post content in Markdown format. Provide markdown OR bodyJson, not both. Markdown cannot represent buttons or linked images — use bodyJson for those.

bodyJsonstring

Post content as a Tiptap document, JSON-stringified (e.g. '{"type":"doc","content":[...]}'). Use instead of markdown when the body needs Subscribe/Share/custom buttons or linked images. Validated server-side; an invalid document is rejected. Provide markdown OR bodyJson, not both.

titlestring required

Title of the post

subtitlestring

Optional subtitle or brief summary

imageUrlstring uri

Optional URL to the post's cover image

imageAltstring

Alternative text describing the cover image. Only used when imageUrl is provided.

status'published' | 'draft'

Status of the post. Default: published

slugstring

Optional URL-friendly identifier for the post. If not provided, will be generated from title

postPreviewstring

Optional preview text for the post. If not provided, will be generated from content

authorIdsstring[]

Optional user ids to credit as the post's authors, in byline order. Each id must be the publication's owner or an active team member — ids from outside the publication are rejected. Defaults to the API key's own user.

scheduledAtinteger

Optional Unix timestamp (milliseconds) to schedule first-publish of the post at a future time. Must be in the future. Cannot be combined with status: 'draft'. When set, the post is created and queued to publish (and send newsletter, if requested) at the specified time. Pass 0 or omit the field for an unscheduled post.

Response

Post created successfully

idstring required

The ID of the created post

status'published' | 'draft' | 'scheduled' required

Final status of the post: 'published' if published immediately, 'draft' if created as a draft, 'scheduled' if queued to publish at scheduledAt

Changes

Changed in 8 of the 61 revisions of this API.410

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, 202617b3077bd1192See the full diff
- ○
  added the new optional request property bodyJson
  new-optional-request-property
- ○
  the request property markdown became optional
  request-property-became-optional
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 14, 202683a5758697642See the full diff
- ○
  added the new optional request property scheduledAt
  new-optional-request-property
- ○
  added the required property status to the response with the 200 status
  response-required-property-added
Mar 20, 20265b94722856861See the full diff
- ○
  added the new optional request property status
  new-optional-request-property
Jan 13, 20266b1ebbf54a872See the full diff
- ○
  request property categories list-of-types was widened by adding types string to media type application/json
  request-property-list-of-types-widened
- ○
  request property sendNewsletter list-of-types was widened by adding types string to media type application/json
  request-property-list-of-types-widened
Dec 16, 202544ce6b0df8f81See the full diff
- ○
  endpoint added
  endpoint-added

Full history