ParagraphDocs
Open the app
GuidesDevelopers

Create a new post

POST
/v1/posts

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.

Authorization

apiKey
headerAuthorizationBearer <token>

API key for authenticating protected endpoints. Pass as Bearer token in Authorization header.

Request Body

Body

application/json
  1. body
markdown?string

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

bodyJson?string

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.

title*string

Title of the post

Lengthlength <= 200
subtitle?string

Optional subtitle or brief summary

Lengthlength <= 300
imageUrl?string

Optional URL to the post's cover image

Formaturi
imageAlt?string

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

Lengthlength <= 1000
sendNewsletter?|

Whether to send an email newsletter to subscribers. Default: false

status?string

Status of the post. Default: published

Value in"published""draft"
slug?string

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

Length1 <= length <= 256
postPreview?string

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

Lengthlength <= 500
categories?array<string>|

Optional array of category tags for the post. Can also be a comma-separated string.

authorIds?array<string>

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.

Items1 <= items <= 20
scheduledAt?integer

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.

Range0 <= value
canonicalUrl?string

Optional canonical URL used in rendered metadata, for a post whose original lives elsewhere. When the publication has its own website set up, a canonical on that site is also where the Paragraph link redirects. This does not change the post's Paragraph permalink.

Formaturi
Lengthlength <= 2048

Response Body

Post created successfully

application/json
  1. response
id*string

The ID of the created post

status*string

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

Value in"published""draft""scheduled"
curl -X POST "https://example.com/v1/posts" \  -H "Content-Type: application/json" \  -d '{    "title": "string"  }'
{  "id": "string",  "status": "published"}

List your posts GET

Retrieve a paginated list of posts from your publication. The publication is identified by the API key provided in the Authorization header. Use the `status` parameter to filter by post status (published, draft, scheduled, or archived). Defaults to published.

Delete a post by slug DELETE

Permanently delete a post using its URL slug. The publication is identified by the API key provided in the Authorization header. **Warning:** This action is irreversible. The post and all related data (notifications and drafts) will be permanently deleted.