Sign in
publications

Update publication settings

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
  • Unknown or removed settings are rejected. The legacy disableHighlights setting is no longer supported and must be removed from requests.
  • 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.
patch/v1/publications/{publicationId}

Path parameters

publicationIdstring required

Unique identifier of the publication to update

Request body

namestring

Display name of the publication

summarystring

Brief description of the publication (max 500 characters)

postListType'feed' | 'grid' | 'full-post'

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'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'

Theme accent color for the publication

headerFont'default' | 'serif' | 'mono'

Font family used for headers

bodyFont'default' | 'serif' | 'mono'

Font family used for body text

showMostPopularboolean

Whether to show the 'most popular posts' widget

hideStatsboolean

Whether to hide stats like subscriber count, post count, and collects

featuredPoststring

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.

enableTableOfContentsboolean

Whether the table of contents is enabled on posts

enableSubscribePopupboolean

Whether to show the subscribe popup to first-time visitors arriving from external links

enableSubscribeScrollboolean

Whether to show the subscribe popup when first-time visitors scroll a post

pinnedPostIdsstring[]

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.

Response

Publication updated successfully — returns the updated publication

idstring required

Unique identifier for the publication

namestring required

Display name of the publication

ownerUserIdstring required

ID of the user who owns this publication

slugstring required

URL-friendly identifier for the publication; accessible at paragraph.com/@[slug]

customDomainstring uri

Custom domain configured for this publication

summarystring

Brief description of the publication (max 500 characters)

logoUrlstring uri

URL to the publication's logo image

postListType'feed' | 'grid' | 'full-post'

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'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'

Theme accent color for the publication

headerFont'default' | 'serif' | 'mono'

Font family used for headers

bodyFont'default' | 'serif' | 'mono'

Font family used for body text

showMostPopularboolean

Whether the 'most popular posts' widget is shown

hideStatsboolean

Whether to hide stats like subscriber count, post count, and collects

featuredPoststring

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.

enableTableOfContentsboolean

Whether the table of contents is enabled on posts

enableSubscribePopupboolean

Whether to show the subscribe popup to first-time visitors arriving from external links

enableSubscribeScrollboolean

Whether to show the subscribe popup when first-time visitors scroll a post

pinnedPostIdsstring[]

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.

Changes

Changed in 5 of the 61 revisions of this API.1152

  • 0b69669d54304See the full diff
    • ●

      removed the request property disableComments

      request-property-removed

    • ●

      removed the request property emailNotifications/newComment

      request-property-removed

    • ●

      removed the optional property disableComments from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property emailNotifications/newComment from the response with the 200 status

      response-optional-property-removed

  • f76f6f333ba86See the full diff
    • ●

      removed the request property disableHighlights

      request-property-removed

    • ●

      removed the request property emailNotifications/newContentCollected

      request-property-removed

    • ●

      removed the request property emailNotifications/newPaidSubscriber

      request-property-removed

    • ●

      removed the optional property disableHighlights from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property emailNotifications/newContentCollected from the response with the 200 status

      response-optional-property-removed

    • ●

      removed the optional property emailNotifications/newPaidSubscriber from the response with the 200 status

      response-optional-property-removed

  • 36c72d74820a11See the full diff
    • ▲

      request property disableComments list-of-types was narrowed by removing types string from media type application/json

      request-property-list-of-types-narrowed

    • ○

      response property disableComments list-of-types was narrowed by removing types string from media type application/json of response 200

      response-property-list-of-types-narrowed

  • 90de04b871335See the full diff
    • ●

      removed the optional property error from the response with the 400 status

      response-optional-property-removed

    • ●

      removed the optional property error from the response with the 401 status

      response-optional-property-removed

    • ●

      removed the optional property error from the response with the 403 status

      response-optional-property-removed

    • ●

      removed the optional property error from the response with the 404 status

      response-optional-property-removed

    • ●

      removed the optional property error from the response with the 500 status

      response-optional-property-removed

  • 79fe03bb40571See the full diff
    • ○

      endpoint added

      endpoint-added