OpenAPI Specification
openapi: 3.1.0
info:
title: Paragraph analytics posts API
version: 1.0.0
description: 'Public API for interacting with Paragraph publications, posts, users, and coined writing.
## Rate Limiting
API requests are rate-limited to ensure fair usage. Contact support@paragraph.com for higher limits.
## Pagination
List endpoints support cursor-based pagination using `cursor` and `limit` parameters.'
contact:
name: Paragraph Support
email: support@paragraph.com
url: https://paragraph.com/support
license:
name: MIT
url: https://opensource.org/licenses/MIT
servers:
- url: https://public.api.paragraph.com/api
description: Production server
security:
- {}
tags:
- name: posts
description: Operations related to posts and content
paths:
/v1/posts/feed:
get:
description: Retrieve a curated, paginated list of posts.
summary: Get posts feed
tags:
- posts
parameters:
- name: cursor
in: query
description: Cursor for pagination
schema:
type: string
- name: limit
in: query
description: 'Maximum number of items to return (1-60, default: 20)'
schema:
default: 20
type: integer
minimum: 1
maximum: 60
- name: includeContent
in: query
description: 'Include full content fields (json, staticHtml, markdown) in the post. Default: false'
schema:
oneOf:
- type: boolean
- type: string
responses:
'200':
description: Feed items retrieved successfully
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
post:
type: object
properties:
id:
type: string
description: Unique identifier for the post
title:
type: string
maxLength: 200
description: Title of the post
imageUrl:
type: string
format: uri
description: Optional URL to the post's main image
publishedAt:
type: string
description: Epoch timestamp when the post was published
updatedAt:
type: string
description: Epoch timestamp when the post was last updated
subtitle:
type: string
maxLength: 300
description: Optional subtitle or brief summary
slug:
type: string
minLength: 1
maxLength: 256
description: URL-friendly identifier for the post; accessible at paragraph.com/@[publicationSlug]/[slug]
staticHtml:
type: string
description: Rendered HTML content of the post
json:
type: string
description: TipTap JSON representation of the post content structure. This is the source of truth that the staticHtml and markdown is generated from
markdown:
type: string
description: Markdown source of the post content
coinId:
type: string
description: ID of the associated coin, if the post is coined
categories:
type: array
items:
type: string
description: Categories/tags associated with this post
authors:
type: array
items:
type: object
properties:
id:
type: string
description: Unique identifier for the user
walletAddress:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: Wallet address of the user
avatarUrl:
type: string
format: uri
description: URL to the user's avatar image
publicationId:
type: string
description: ID of the publication this user belongs to
name:
type: string
description: Display name of the user
bio:
type: string
maxLength: 500
description: Brief biography of the user (max 500 characters)
farcaster:
type: object
properties:
username:
type: string
description: Farcaster username
displayName:
type: string
description: Farcaster display name
fid:
type: number
description: Farcaster fid
required:
- username
- displayName
- fid
description: Farcaster profile information, if linked
required:
- id
- publicationId
description: Authors of this post
authorIds:
type: array
items:
type: string
description: IDs of the authors of this post
views:
type: number
description: Total views. Only included when fetching your own posts via GET /v1/posts
status:
type: string
enum:
- published
- draft
- scheduled
- archived
description: Current publish status. Only set on authenticated endpoints (listOwn, getById for your own post). Use this instead of publishedAt to determine publish state — publishedAt is preserved across unpublishing.
required:
- id
- title
- slug
description: The post content
publication:
type: object
properties:
id:
type: string
description: Unique identifier for the publication
name:
type: string
description: Display name of the publication
ownerUserId:
type: string
description: ID of the user who owns this publication
slug:
type: string
minLength: 1
maxLength: 256
description: URL-friendly identifier for the publication; accessible at paragraph.com/@[slug]
customDomain:
type: string
format: uri
description: Custom domain configured for this publication
summary:
type: string
maxLength: 500
description: Brief description of the publication (max 500 characters)
logoUrl:
type: string
format: uri
description: URL to the publication's logo image
postListType:
type: string
enum:
- feed
- grid
- full-post
description: Homepage layout. 'feed' is a single-column list of cards, 'grid' is a 3-column grid, 'full-post' shows full posts in a single column.
themeColor:
type: string
enum:
- default
- orange-500
- rose-600
- pink-500
- fuchsia-600
- purple-600
- violet-600
- indigo-600
- blue-600
- sky-600
- cyan-600
- teal-600
- emerald-600
- green-600
- lime-600
- yellow-700
- amber-600
- orange-600
- stone-800
- rose-900
- indigo-950
- teal-950
- lime-950
- orange-950
description: Theme accent color for the publication
headerFont:
type: string
enum:
- default
- serif
- mono
description: Font family used for headers
bodyFont:
type: string
enum:
- default
- serif
- mono
description: Font family used for body text
showMostPopular:
type: boolean
description: Whether the 'most popular posts' widget is shown
hideStats:
type: boolean
description: Whether to hide stats like subscriber count, post count, and collects
featuredPost:
type: string
minLength: 1
description: Featured post selector. Use 'latest' for the most recent post, 'popular' for the most-viewed post, 'disabled' to hide the featured slot, or the ID of a specific post in this publication.
disableComments:
oneOf:
- type: boolean
- type: string
enum:
- on-platform
description: Comment visibility. true disables all comments, false enables them, 'on-platform' hides on-Paragraph comments while keeping Farcaster comments.
disableHighlights:
type: boolean
description: Whether to disable highlights on this publication's posts
enableTableOfContents:
type: boolean
description: Whether the table of contents is enabled on posts
enableSubscribePopup:
type: boolean
description: Whether to show the subscribe popup to first-time visitors arriving from external links
enableSubscribeScroll:
type: boolean
description: Whether to show the subscribe popup when first-time visitors scroll a post
pinnedPostIds:
type: array
items:
type: string
description: Ordered list of post IDs pinned to the top of the publication's homepage. Pinned posts render in their own section above the regular feed.
emailNotifications:
type: object
properties:
newComment:
type: boolean
description: Email the writer when someone comments on a post
newSubscriber:
type: boolean
description: Email the writer when a new free subscriber signs up
newPaidSubscriber:
type: boolean
description: Email the writer when a new paid subscriber signs up
newContentCollected:
type: boolean
description: Email the writer when someone collects their content
description: Owner-side email notification toggles
required:
- id
- name
- ownerUserId
- slug
description: The publication this post belongs to
user:
type: object
properties:
id:
type: string
description: Unique identifier for the user
walletAddress:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: Wallet address of the user
avatarUrl:
type: string
format: uri
description: URL to the user's avatar image
publicationId:
type: string
description: ID of the publication this user belongs to
name:
type: string
description: Display name of the user
bio:
type: string
maxLength: 500
description: Brief biography of the user (max 500 characters)
farcaster:
type: object
properties:
username:
type: string
description: Farcaster username
displayName:
type: string
description: Farcaster display name
fid:
type: number
description: Farcaster fid
required:
- username
- displayName
- fid
description: Farcaster profile information, if linked
required:
- id
- publicationId
description: The user who owns the publication this post belongs to
required:
- post
- publication
- user
description: Array of items in this page
pagination:
type: object
properties:
cursor:
type: string
description: Cursor for fetching the next page of results
hasMore:
type: boolean
description: Whether more results are available
total:
type: number
description: Total number of items available
required:
- hasMore
required:
- items
- pagination
'400':
description: Invalid request parameters
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
description: Always false for error responses
msg:
type: string
description: Human-readable error message
required:
- success
- msg
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
description: Always false for error responses
msg:
type: string
description: Human-readable error message
required:
- success
- msg
operationId: getPostsFeed
x-mint:
mcp:
enabled: true
name: get-posts-feed
description: Get curated home feed posts
x-codeSamples:
- lang: typescript
label: Get feed posts with pagination
source: 'import { ParagraphAPI } from "@paragraph-com/sdk"
const api = new ParagraphAPI()
const { items, pagination } = await api.feed.get({ limit: 20 })'
/v1/posts/tag/{tag}:
get:
description: Retrieve a paginated list of posts with a specific tag, sorted by publish date (newest first)
summary: Get posts by tag
tags:
- posts
parameters:
- name: tag
in: path
required: true
schema:
type: string
minLength: 1
description: Tag to filter posts by
- name: cursor
in: query
description: Cursor for pagination
schema:
type: string
- name: limit
in: query
description: 'Maximum number of items to return (1-100, default: 10)'
schema:
default: 10
type: integer
minimum: 1
maximum: 100
- name: includeContent
in: query
description: 'Include full content fields (json, staticHtml, markdown) in the post. Default: false'
schema:
oneOf:
- type: boolean
- type: string
responses:
'200':
description: Posts retrieved successfully
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
id:
type: string
description: Unique identifier for the post
title:
type: string
maxLength: 200
description: Title of the post
imageUrl:
type: string
format: uri
description: Optional URL to the post's main image
publishedAt:
type: string
description: Epoch timestamp when the post was published
updatedAt:
type: string
description: Epoch timestamp when the post was last updated
subtitle:
type: string
maxLength: 300
description: Optional subtitle or brief summary
slug:
type: string
minLength: 1
maxLength: 256
description: URL-friendly identifier for the post; accessible at paragraph.com/@[publicationSlug]/[slug]
staticHtml:
type: string
description: Rendered HTML content of the post
json:
type: string
description: TipTap JSON representation of the post content structure. This is the source of truth that the staticHtml and markdown is generated from
markdown:
type: string
description: Markdown source of the post content
coinId:
type: string
description: ID of the associated coin, if the post is coined
categories:
type: array
items:
type: string
description: Categories/tags associated with this post
authors:
type: array
items:
type: object
properties:
id:
type: string
description: Unique identifier for the user
walletAddress:
type: string
pattern: ^0x[a-fA-F0-9]{40}$
description: Wallet address of the user
avatarUrl:
type: string
format: uri
description: URL to the user's avatar image
publicationId:
type: string
description: ID of the publication this user belongs to
name:
type: string
description: Display name of the user
bio:
type: string
maxLength: 500
description: Brief biography of the user (max 500 characters)
farcaster:
type: object
properties:
username:
type: string
description: Farcaster username
displayName:
type: string
description: Farcaster display name
fid:
type: number
description: Farcaster fid
required:
- username
- displayName
- fid
description: Farcaster profile information, if linked
required:
- id
- publicationId
description: Authors of this post
authorIds:
type: array
items:
type: string
description: IDs of the authors of this post
views:
type: number
description: Total views. Only included when fetching your own posts via GET /v1/posts
status:
type: string
enum:
- published
- draft
- scheduled
- archived
description: Current publish status. Only set on authenticated endpoints (listOwn, getById for your own post). Use this instead of publishedAt to determine publish state — publishedAt is preserved across unpublishing.
required:
- id
- title
- slug
description: Array of items in this page
pagination:
type: object
properties:
cursor:
type: string
description: Cursor for fetching the next page of results
hasMore:
type: boolean
description: Whether more results are available
total:
type: number
description: Total number of items available
required:
- hasMore
required:
- items
- pagination
'400':
description: Invalid request parameters
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
description: Always false for error responses
msg:
type: string
description: Human-readable error message
required:
- success
- msg
'500':
description: Internal server error
content:
application/json:
schema:
type: object
properties:
success:
type: boolean
enum:
- false
description: Always false for error responses
msg:
type: string
description: Human-readable error message
required:
- success
- msg
operationId: getPostsByTag
x-mint:
mcp:
enabled: true
name: list-posts-by-tag
description: Get posts with a specific tag
x-codeSamples:
- lang: typescript
label: Get posts by tag with pagination
source: 'import { ParagraphAPI } from "@paragraph-com/sdk"
const api = new ParagraphAPI()
const { items, pagination } = await api.posts.get({ tag: "crypto", limit: 20 })'
/v1/publications/{publicationId}/posts:
get:
description: Retrieve a paginated list of published posts from a publication
summary: Get posts in a publication
tags:
- posts
parameters:
- name: publicationId
in: path
required: true
schema:
type: string
description: Unique identifier of the publication
- name: cursor
in: query
description: Cursor for pagination
schema:
type: string
- name: limit
in: query
description: 'Maximum number of items to return (1-100, default: 10)'
schema:
default: 10
type: integer
minimum: 1
maximum: 100
- name: includeContent
in: query
description: 'Include full content fields (markdown, json, staticHtml). Default: false'
schema:
oneOf:
- type: boolean
- type: string
responses:
'200':
description: Posts retrieved successfully
content:
application/json:
schema:
type: object
properties:
items:
type: array
items:
type: object
properties:
id:
type: string
description: Unique identifier for the post
title:
type: string
maxLength: 200
description: Title of the post
imageUrl:
type: string
format: uri
description: Optional URL to the post's main image
publishedAt:
type: string
description: Epoch timestamp when the post was published
updatedAt:
type: string
description: Epoch timestamp when the post was last updated
subtitle:
type: string
maxLength: 300
description: Optional subtitle or brief summary
slug:
type: string
minLength: 1
maxLength: 256
description: URL-friendly identifier for the post; accessible at paragraph.com/@[publicationSlug]/[slug]
staticHtml:
type: string
description: Rendered HTML content of the post
json:
type: string
description: TipTap JSON representation of the post content structure. This is the source of truth that the staticHtml and markdown is generated from
markdown:
type: string
description: Markdown source of the post content
coinId:
type: string
description: ID of the associated coin, if the post is coined
categories:
type: array
items:
type: string
# --- truncated at 32 KB (109 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paragraph/refs/heads/main/openapi/paragraph-posts-api-openapi.yml