ParagraphDocs
Open the app
GuidesDevelopers

List your posts

GET
/v1/posts

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.

Authorization

apiKey
headerAuthorizationBearer <token>

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

Query Parameters

cursor?string

Cursor for pagination

limit?integer

Maximum number of items to return (1-100, default: 10)

Range1 <= value <= 100
Default10
includeContent?|

Include full content fields (markdown, json, staticHtml). Default: false

status?string

Filter by post status. Default: published

Value in"published""draft""scheduled""archived"

Response Body

Posts retrieved successfully

application/json
  1. response
items*array<>

Array of items in this page

pagination*
curl -X GET "https://example.com/v1/posts"
{  "items": [    {      "id": "string",      "title": "string",      "imageUrl": "http://example.com",      "imageAlt": "string",      "publishedAt": "string",      "updatedAt": "string",      "subtitle": "string",      "slug": "string",      "staticHtml": "string",      "json": "string",      "markdown": "string",      "coinId": "string",      "categories": [        "string"      ],      "canonicalUrl": "http://example.com",      "publishOnline": true,      "communityId": "string",      "authors": [        {          "id": "string",          "walletAddress": "string",          "avatarUrl": "http://example.com",          "publicationId": "string",          "name": "string",          "bio": "string"        }      ],      "authorIds": [        "string"      ],      "views": 0,      "status": "published"    }  ],  "pagination": {    "cursor": "string",    "hasMore": true,    "total": 0  }}

Get post by publication slug and post slug GET

Retrieve a post using its publication's slug and the post's slug. This is useful for building user-facing URLs.

Create a new post 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.