Sign in

v52

latestOpenAPI 3.1.0MITraw.githubusercontent.com2026-07-21450373.3 KB
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

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