Skip to content

Quickstart

This quickstart takes you from nothing to content on screen. You create a content model in the console, publish an entry, create a public API key, read the entry with curl, and then render it in a new Next.js app with @plenary/client. It takes about fifteen minutes.

  • Node.js 20 or later and npm.
  • A Plenary instance and an account that can create models and API keys (the admin role can). See the next section if you do not have one yet.

Throughout this page, https://your-instance.plenarycms.io stands for your instance’s URL. Replace it with your own. On a self-hosted install it is the URL you deployed to, such as https://cms.example.com.

Pick one:

  • Plenary Cloud. Start a free trial at plenarycms.com/signup. When provisioning finishes you get an instance at https://<subdomain>.plenarycms.io and can sign in to its console at https://<subdomain>.plenarycms.io/cms with the email and password you chose. Details: Plenary Cloud.
  • Self-hosted. Run the Plenary Docker image with MongoDB and create the first admin user. Details: Self-Hosted Install.

Every instance starts with one site whose key is default. A site is one website or app that the instance serves; content reads always name a site. You can see your sites, and their keys, under Admin Settings → Site Management in the console.

A content model defines the fields an entry can hold. Create one for blog posts:

  1. Sign in to the console at https://your-instance.plenarycms.io/cms.
  2. In the sidebar, open Content, then click New model.
  3. On the Settings tab, enter Name (singular) Post and Name (plural) Posts. The Key fills in as post. The key is how the API names this model, so keep it.
  4. Leave Kind as Collection.
  5. Open the Fields tab and click Add field. Enter Name Title, leave Type as Text, and turn on Title field. The key fills in as title.
  6. Click Add field again. Enter Name Body and leave Type as Text. The key fills in as body.
  7. Click Save model. The model belongs to the site selected in the console’s site switcher, default on a new instance.

New models are Public by default, which means public API keys can read their published entries.

  1. Go back to Content. On the Post card, click Open entries.
  2. Click Add Post.
  3. Enter Title Hello, Plenary and Body My first published entry.. The URL Slug on the right fills in as hello-plenary.
  4. Open the menu on the arrow next to Save Changes and choose Save and Publish.

The status badge changes from Draft to Published. Only published entries are visible to public API keys.

Your site reads content with an API key, not a user login.

  1. In the sidebar, open Access Management → API Keys and click New.
  2. Enter a Name, such as Quickstart site.
  3. Under Type, choose Public. Public keys can only read published content, so they are safe to use in a browser.
  4. Under Site, check that your site is selected. A public key belongs to exactly one site.
  5. Click Create key.
  6. Copy the token. Public keys start with pln_pub_. You can come back to the key’s panel later to copy it again.

Put the values in your shell, then list the model’s published entries:

Terminal window
export PLENARY_BASE_URL="https://your-instance.plenarycms.io"
export PLENARY_API_KEY="pln_pub_your_key_here"
curl "$PLENARY_BASE_URL/api/v1/content/post?site_key=default&locale=en-us" \
-H "X-API-KEY: $PLENARY_API_KEY"

The response is a JSON array of entries:

[
{
"id": "01fb8dda-cf9e-4939-9ba0-971aa2310864",
"site_key": "default",
"model_key": "post",
"slug": "hello-plenary",
"locale": "en-us",
"title": "Hello, Plenary",
"status": "published",
"published_at": "2026-10-07T09:13:45.714Z",
"publish_at": null,
"unpublish_at": null,
"created_at": "2026-10-07T09:13:45.625Z",
"updated_at": "2026-10-07T09:13:45.714Z",
"data": {
"body": "My first published entry.",
"title": "Hello, Plenary"
},
"folder_id": null,
"path": "/"
}
]

Your field values are under data, keyed by field key. Fetch one entry by its slug:

Terminal window
curl "$PLENARY_BASE_URL/api/v1/content/post/hello-plenary?site_key=default&locale=en-us" \
-H "X-API-KEY: $PLENARY_API_KEY"

This returns the single entry object. If you get an error instead, check these first:

Response Likely cause
401 {"error":{"code":"authentication_required"}} The X-API-KEY header is missing.
401 {"error":{"code":"api_key_invalid"}} The token is wrong, or the key was deleted or is inactive.
404 {"error":{"code":"entry_not_found"}} The slug is wrong, the entry is still a draft, or the locale does not match.

If your site’s default locale is not en-us, use the locale shown on the site under Site Management. See Errors for every error code.

Create a Next.js app with the App Router and TypeScript, then add the Plenary client:

Terminal window
npx create-next-app@latest my-plenary-site --yes
cd my-plenary-site
npm install @plenary/client

The commands below assume the defaults create-next-app picks with --yes: TypeScript, the App Router, no src/ directory, and the @/* import alias. If your app uses a src/ directory, put the app/ and lib/ files below inside src/.

Add your instance details as environment variables:

.env.local
PLENARY_BASE_URL=https://your-instance.plenarycms.io
PLENARY_API_KEY=pln_pub_your_key_here
PLENARY_SITE_KEY=default
PLENARY_LOCALE=en-us

These variables have no NEXT_PUBLIC_ prefix, so they stay on the server. The pages below are React Server Components, so the API key is never sent to the browser.

Create one shared client. baseUrl is the instance origin, without /api/v1. siteKey and locale are sent with every read.

lib/plenary.ts
import { createClient } from "@plenary/client";
export const plenary = createClient({
baseUrl: process.env.PLENARY_BASE_URL!,
apiKey: process.env.PLENARY_API_KEY!,
siteKey: process.env.PLENARY_SITE_KEY ?? "default",
locale: process.env.PLENARY_LOCALE ?? "en-us",
});
/** The fields of the `post` model, keyed by field key. */
export type Post = {
title: string;
body?: string;
};

List posts on the home page. listEntries returns { items }, newest first with this sort:

app/page.tsx
import Link from "next/link";
import { plenary, type Post } from "@/lib/plenary";
export default async function Home() {
const { items } = await plenary.listEntries<Post>("post", {
sort: { published_at: "desc" },
});
return (
<main>
<h1>Posts</h1>
<ul>
{items.map((post) => (
<li key={post.id}>
<Link href={`/posts/${post.slug}`}>{post.data.title}</Link>
</li>
))}
</ul>
</main>
);
}

Render one post by slug. getEntry throws PlenaryNotFoundError for a missing or unpublished entry, which this page turns into a Next.js 404:

app/posts/[slug]/page.tsx
import { notFound } from "next/navigation";
import { PlenaryNotFoundError } from "@plenary/client";
import { plenary, type Post } from "@/lib/plenary";
export default async function PostPage({
params,
}: {
params: Promise<{ slug: string }>;
}) {
const { slug } = await params;
try {
const post = await plenary.getEntry<Post>("post", slug);
return (
<main>
<h1>{post.data.title}</h1>
<p>{post.data.body}</p>
</main>
);
} catch (err) {
if (err instanceof PlenaryNotFoundError) notFound();
throw err;
}
}

Start the dev server:

Terminal window
npm run dev

Open http://localhost:3000. You see Posts with a link to Hello, Plenary; click it to see the body. Edit the entry in the console, save and publish, and reload the page to see the change.

  • A content model (post) with two fields (title, body).
  • A published entry with the slug hello-plenary.
  • A public API key scoped to your site.
  • A Next.js app that reads published content server-side with @plenary/client.