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.
Prerequisites
Section titled “Prerequisites”- Node.js 20 or later and npm.
- A Plenary instance and an account that can create models and API keys (the
adminrole 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.
1. Get an instance
Section titled “1. Get an instance”Pick one:
- Plenary Cloud. Start a free trial at plenarycms.com/signup. When provisioning finishes you get an instance at
https://<subdomain>.plenarycms.ioand can sign in to its console athttps://<subdomain>.plenarycms.io/cmswith 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.
2. Create a content model
Section titled “2. Create a content model”A content model defines the fields an entry can hold. Create one for blog posts:
- Sign in to the console at
https://your-instance.plenarycms.io/cms. - In the sidebar, open Content, then click New model.
- On the Settings tab, enter Name (singular)
Postand Name (plural)Posts. The Key fills in aspost. The key is how the API names this model, so keep it. - Leave Kind as Collection.
- Open the Fields tab and click Add field. Enter Name
Title, leave Type as Text, and turn on Title field. The key fills in astitle. - Click Add field again. Enter Name
Bodyand leave Type as Text. The key fills in asbody. - Click Save model. The model belongs to the site selected in the console’s site switcher,
defaulton a new instance.
New models are Public by default, which means public API keys can read their published entries.
3. Add and publish an entry
Section titled “3. Add and publish an entry”- Go back to Content. On the Post card, click Open entries.
- Click Add Post.
- Enter Title
Hello, Plenaryand BodyMy first published entry.. The URL Slug on the right fills in ashello-plenary. - 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.
4. Create a public API key
Section titled “4. Create a public API key”Your site reads content with an API key, not a user login.
- In the sidebar, open Access Management → API Keys and click New.
- Enter a Name, such as
Quickstart site. - Under Type, choose Public. Public keys can only read published content, so they are safe to use in a browser.
- Under Site, check that your site is selected. A public key belongs to exactly one site.
- Click Create key.
- Copy the token. Public keys start with
pln_pub_. You can come back to the key’s panel later to copy it again.
5. Fetch the entry with curl
Section titled “5. Fetch the entry with curl”Put the values in your shell, then list the model’s published entries:
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:
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.
6. Render it in Next.js
Section titled “6. Render it in Next.js”Create a Next.js app with the App Router and TypeScript, then add the Plenary client:
npx create-next-app@latest my-plenary-site --yescd my-plenary-sitenpm install @plenary/clientThe 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:
PLENARY_BASE_URL=https://your-instance.plenarycms.ioPLENARY_API_KEY=pln_pub_your_key_herePLENARY_SITE_KEY=defaultPLENARY_LOCALE=en-usThese 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.
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:
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:
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:
npm run devOpen 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.
What you built
Section titled “What you built”- 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.
Next steps
Section titled “Next steps”- Blog with Next.js: a fuller blog with images, references, and metadata.
- Fields: every field type you can add to a model.
- Content API: filtering, sorting, pagination, and locales.
- @plenary/client: every client method and option.
- Page Builder: let editors lay out pages visually with your own components.