Skip to main content
Use the publive-cms-sdk package when you want a typed client for Publive content delivery and selected CMS utilities.
Keep your Publive credentials on the server. Do not initialize this SDK in client-side code.

​
Overview

This page gives you a practical view of the SDK surface, the main methods available in each namespace, and the places where the existing API reference is still the better source for endpoint-level detail.

​
Install the package

npm install https://cdn.thepublive.com/pl-modules/node/publive-cms-sdk-0.0.5.tgz
Use Node.js 18 or later so you have a supported fetch runtime by default.

​
Initialize the SDK

import { Publive } from "publive-cms-sdk";

const sdk = new Publive({
  publisherId: 12345,
  environment: "production",
  apiKey: process.env.PUBLIVE_API_KEY!,
  apiSecret: process.env.PUBLIVE_API_SECRET!,
});

​
Configuration

FieldRequiredDescription
publisherIdYesYour Publive publisher ID
environmentYesproduction, beta, or development
apiKeyYesYour Publive API key
apiSecretYesYour Publive API secret
publisherSlugNoOptional publisher slug for app-level usage

​
Core services

The Publive class exposes five service areas:
ServiceUse it for
sdk.contentPosts, categories, tags, members, and content identification
sdk.authPublisher-level metadata
sdk.utilsNavbar, footer, slots, and forms
sdk.deliveryLow-level Content Delivery API requests
sdk.managementLow-level CMS API requests

​
Where the SDK fits

The SDK works well as a server-side client for common Publive workflows. It provides typed helpers for content retrieval, layout data, slots, forms, and publisher metadata, while also handling authentication headers, retries, and timeouts in one place. For endpoint-by-endpoint behavior, request and response details, or flows outside the exported namespaces, the API reference remains the better companion.

​
SDK surface

The tables below summarize the current callable surface exposed by the SDK.

​
sdk.content

NamespaceMethods
postfetchById, fetchBySlug, fetchByLegacyURL, fetchList, fetchFeaturedPosts, fetchPostByCategory, fetchPostByTag, fetchPostByAuthor, fetchPostByCollectionSlug
categoryfetchById, fetchBySlug, fetchList
tagfetchById, fetchBySlug, fetchList
memberfetchById, fetchBySlug, fetchList
content rootidentify

​
sdk.utils

NamespaceMethods
layoutfetchNavbar, fetchFooter
slotfetchSlots
formfetchForm, submitForm

​
Other namespaces

NamespaceMethods
sdk.authfetchPublisher
sdk.deliveryget, post, put, delete
sdk.managementget, post, put, delete

​
Fetch content

​
Work with posts

const latestPosts = await sdk.content.post.fetchList({
  queryParams: {
    page: 1,
    limit: 10,
  },
});

const post = await sdk.content.post.fetchBySlug("welcome-to-publive");
const featured = await sdk.content.post.fetchFeaturedPosts();
Available post helpers:
  • fetchById(id)
  • fetchBySlug(slug)
  • fetchByLegacyURL(legacyUrl)
  • fetchList(options)
  • fetchFeaturedPosts(options)
  • fetchPostByCategory(categoryId, options)
  • fetchPostByTag(tagId, options)
  • fetchPostByAuthor(contributorId, options)
  • fetchPostByCollectionSlug(collectionSlug, options)

​
Work with categories, tags, and authors

const categories = await sdk.content.category.fetchList({
  queryParams: { limit: 20 },
});

const category = await sdk.content.category.fetchBySlug("technology");
const tag = await sdk.content.tag.fetchBySlug("ai");
const author = await sdk.content.member.fetchBySlug("editor-desk");
Each content service supports:
  • fetchById(id)
  • fetchBySlug(slug)
  • fetchList(options)

​
Identify a URL or slug

Use identify when you need to resolve a slug or legacy URL to its Publive content type. For the HTTP endpoint details, see [Identify content](/api-reference/content-delivery/identify- content). 
const result = await sdk.content.identify("welcome-to-publive");

console.log(result.data.type);
console.log(result.data.url);
console.log(result.data.content?.title);
identify() returns metadata about the resolved URL, including type, url, status_code, and optional content.

​
Fetch layout and utility data

const navbar = await sdk.utils.layout.fetchNavbar();
const footer = await sdk.utils.layout.fetchFooter();
const slots = await sdk.utils.slot.fetchSlots();
Forms are available through the management client: 
const form = await sdk.utils.form.fetchForm();

await sdk.utils.form.submitForm("form-id", {
  email: "reader@example.com",
  name: "A Reader",
});

​
Fetch publisher metadata

const publisher = await sdk.auth.fetchPublisher();
This returns publisher-level configuration and metadata for the current credentials.

​
Use low-level clients

The low-level delivery and management clients are useful when you need a request that does not yet have a dedicated helper. 
const posts = await sdk.delivery.get("/posts/", {
  queryParams: { limit: 5 },
});

const cmsResponse = await sdk.management.get("/form/");
They are most useful when:
  • the SDK already supports the authentication and environment handling you need
  • the helper method you want does not exist yet
  • you already know the exact endpoint from the API reference
In most cases, the higher-level namespaces are easier to work with because they already encode the common paths and usage patterns.

​
Request options

Most SDK methods accept a RequestOptions object.
OptionDescription
headersAdd custom request headers
queryParamsAppend query string filters and pagination
responseTypeParse as json, text, or blob
timeoutOverride request timeout in milliseconds
retryOverride retry attempts
versionInsert an API version into the request path
Example: 
const response = await sdk.content.post.fetchList({
  queryParams: {
    page: 1,
    limit: 20,
    "categories.id__eq": 12,
  },
  timeout: 15000,
  retry: 1,
});

​
Use the media URL helper

The package also exports a lightweight helper namespace for image URL transforms. 
import { publive } from "publive-cms-sdk";

const url = "https://img-cdn.publive.online/fit-in/100x100/filters:format(webp)/image.png";

const smallImage = publive.utils.lib.convertMediaURL(url, "small");
const customImage = publive.utils.lib.convertMediaURL(url, "custom", {
  width: 800,
  height: 450,
});
Supported presets include small, medium, default, large, xlarge, portrait, and custom.

​
Exported enums and helpers

The package also exports constants, enums, types, and error classes that are useful when building app logic. Common exports include:
  • PostCollectionSlug
  • PostType
  • RSSPostType
  • CDSAdvancedFilter
  • PLException
  • PLAPIException
  • publive.utils.lib.convertMediaURL

​
Handle errors

The SDK throws typed API errors for failed delivery requests. 
import { PLAPIException } from "publive-cms-sdk";

try {
  await sdk.content.post.fetchBySlug("missing-slug");
} catch (error) {
  if (error instanceof PLAPIException) {
    console.error(error.status);
    console.error(error.message);
  }
}

​
Behavior notes

These details are easy to miss and are useful to keep in mind while building:
  • The SDK is designed for server-side use because it requires apiKey and apiSecret.
  • sdk.utils.form uses the CMS management client under the hood, not the delivery client.
  • sdk.delivery and sdk.management do not handle failed responses in exactly the same way.
  • version in RequestOptions rewrites the request path to include an API version segment.
  • environment changes the base host used by the SDK: production, beta, and development do not hit the same backend.
  • retry and timeout can be overridden per request instead of only at initialization time.

​
Map SDK methods to existing docs

This table points to the existing API docs when you want more endpoint-level detail without repeating that material here.
SDK areaSee also
sdk.content.postPost listing, Post details, Post details by URL, Live blog updates
sdk.content.categoryCategory listing, Category details
sdk.content.tagTag listing, Tag details
sdk.content.memberAuthor listing, Author details
sdk.auth, sdk.utils.layout, sdk.utils.slotPublisher data, Navbar, Footer, Active slots
sdk.utils.form, sdk.managementForm submission

​
Example: server route

This pattern works well in a Next.js route handler or any server-only endpoint. 
import { Publive } from "publive-cms-sdk";

const sdk = new Publive({
  publisherId: Number(process.env.PUBLIVE_PUBLISHER_ID),
  environment: "production",
  apiKey: process.env.PUBLIVE_API_KEY!,
  apiSecret: process.env.PUBLIVE_API_SECRET!,
});

export async function getHomepageData() {
  const [posts, navbar, footer] = await Promise.all([
    sdk.content.post.fetchList({ queryParams: { limit: 6 } }),
    sdk.utils.layout.fetchNavbar(),
    sdk.utils.layout.fetchFooter(),
  ]);

  return {
    posts: posts.data,
    navbar: navbar.data,
    footer: footer.data,
  };
}

Content Delivery API

See the underlying delivery endpoints

Content Management API

See CMS endpoints used by form helpers

Next.js integration

Use the SDK in a server-rendered frontend

Decoupled frontend

Build a custom frontend on top of Publive