Paragraph publications API
Operations related to publications
OpenAPI Specification
openapi: 3.1.0
info:
title: Paragraph analytics publications 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: publications
description: Operations related to publications
paths:
/v1/publications/{publicationId}:
get:
description: Retrieve detailed information about a specific publication
summary: Get publication by ID
tags:
- publications
parameters:
- name: publicationId
in: path
required: true
schema:
type: string
description: Unique identifier of the publication
responses:
'200':
description: Publication details retrieved successfully
content:
application/json:
schema:
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
'404':
description: Publication not found
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: getPublicationById
x-mint:
mcp:
enabled: true
name: get-publication-by-id
description: Get a publication by its unique ID
x-codeSamples:
- lang: typescript
label: Get publication by ID
source: 'import { ParagraphAPI } from "@paragraph-com/sdk"
const api = new ParagraphAPI()
const publication = await api.publications.get({ id: "BMV6abfvCSUl51ErCVzd" }).single()'
patch:
description: 'Update settings for a publication. The publication is identified by the API key provided in the Authorization header, and the path `:publicationId` must match the publication that owns the API key.
**Behavior:**
- Only provided fields are updated; omitted fields remain unchanged
- Set `featuredPost` to `"latest"`, `"popular"`, `"disabled"`, or a specific post ID. The post must belong to this publication.
- `pinnedPostIds` replaces the existing pinned list. Pinned posts are hidden from the regular feed (they show in their own section), and unpinned posts return to the feed.
- `emailNotifications` is merged onto the current settings; only the toggles you send are changed.'
summary: Update publication settings
tags:
- publications
parameters:
- name: publicationId
in: path
required: true
schema:
type: string
description: Unique identifier of the publication to update
requestBody:
description: Body
content:
application/json:
schema:
type: object
properties:
name:
type: string
minLength: 1
maxLength: 100
description: Display name of the publication
summary:
type: string
maxLength: 500
description: Brief description of the publication (max 500 characters)
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 to show the 'most popular posts' widget
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 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
minLength: 1
maxLength: 64
maxItems: 50
description: Ordered list of post IDs to pin to the top of the homepage. Each ID must belong to this publication. Replaces the existing pinned list. Maximum 50 IDs.
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
responses:
'200':
description: Publication updated successfully — returns the updated publication
content:
application/json:
schema:
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
'400':
description: Invalid request — check field values
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
'401':
description: Invalid or missing API key
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
'403':
description: API key does not have access to this publication
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
'404':
description: Publication not found
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: updatePublication
x-mint:
mcp:
enabled: true
name: update-publication
description: Update settings for a publication, including theme, featured post, and behavior toggles
x-codeSamples:
- lang: typescript
label: Set a featured post
source: "import { ParagraphAPI } from \"@paragraph-com/sdk\"\n\nconst api = new ParagraphAPI({ apiKey: \"your-api-key\" })\nawait api.publications.update({\n id: \"BMV6abfvCSUl51ErCVzd\",\n featuredPost: \"3T2PQZlsdQtigUp4fhlb\",\n})"
- lang: typescript
label: Update theme settings
source: "import { ParagraphAPI } from \"@paragraph-com/sdk\"\n\nconst api = new ParagraphAPI({ apiKey: \"your-api-key\" })\nawait api.publications.update({\n id: \"BMV6abfvCSUl51ErCVzd\",\n themeColor: \"indigo-600\",\n headerFont: \"serif\",\n postListType: \"grid\",\n})"
- lang: bash
label: Disable comments using curl
source: "curl -X PATCH \"https://public.api.paragraph.com/api/v1/publications/BMV6abfvCSUl51ErCVzd\" \\\n -H \"Authorization: Bearer your-api-key\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"disableComments\": true}'"
security:
- apiKey: []
/v1/publications/slug/{slug}:
get:
description: Retrieve publication details using its URL-friendly slug. Optionally include an @ before the slug.
summary: Get publication by slug
tags:
- publications
parameters:
- name: slug
in: path
required: true
schema:
type: string
minLength: 1
maxLength: 256
description: URL-friendly identifier of the publication
responses:
'200':
description: Publication details retrieved successfully
content:
application/json:
schema:
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
'404':
description: Publication not found
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
ope
# --- truncated at 32 KB (42 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/paragraph/refs/heads/main/openapi/paragraph-publications-api-openapi.yml