This is the full developer documentation for Plenary # Building with AI Agents > Point an AI coding agent at these docs, give it the right credentials, and avoid the mistakes agents most often make with Plenary. Many Plenary sites are built with help from an AI coding agent such as Claude Code, Cursor, or Copilot. These docs are written to be read by those agents as well as by people. This page explains how to hand the docs to an agent, what access to give it, and which Plenary rules it should follow. ## Give your agent the docs [Section titled “Give your agent the docs”](#give-your-agent-the-docs) Every page of this site is published in machine-friendly forms: | URL | What it contains | Use it when | | --------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------- | | [`/llms.txt`](https://docs.plenarycms.com/llms.txt) | A short summary of Plenary and an index of every page, each with a one-line description and a Markdown link. | The agent can fetch pages on demand. This is the best starting point. | | [`/llms-full.txt`](https://docs.plenarycms.com/llms-full.txt) | Every page concatenated into one Markdown file. | The agent cannot browse, or you want to give it the whole manual at once. | | [`/llms-small.txt`](https://docs.plenarycms.com/llms-small.txt) | The same, with notes, tips, and collapsed details removed. | The full file is too large for the agent’s context window. | Any single page is also available as raw Markdown by adding `.md` to its URL. For example, the Content API reference is at `https://docs.plenarycms.com/reference/content-api.md`. Topic bundles live under `/_llms-txt/`: `guides.txt`, `examples.txt`, and `api-and-sdk-reference.txt`. Use one when an agent needs a single area in depth. ## Add Plenary to your project instructions [Section titled “Add Plenary to your project instructions”](#add-plenary-to-your-project-instructions) Most agents read a project instruction file, such as `AGENTS.md`, `CLAUDE.md`, or `.cursor/rules`. Add a short block so the agent knows where the docs are and which rules matter. Adjust the values to match your project. AGENTS.md ```md ## Plenary CMS This site reads its content from Plenary. - Docs index: https://docs.plenarycms.com/llms.txt (append `.md` to any docs URL for Markdown). - Instance: https://your-instance.plenarycms.io, site key `main`, locale `en-us`. - Packages: @plenary/client for reads and forms, @plenary/react for page-builder rendering, @plenary/next for webhook revalidation, @plenary/cli for model YAML. - Env vars: PLENARY_BASE_URL, PLENARY_SITE_KEY, PLENARY_LOCALE, PLENARY_API_KEY (the site's public key), PLENARY_CLI_API_KEY (the CLI's private key; never read it from site code). - Content models are kept as YAML in `plenary/models/` and applied with `npx plenary metadata push`. Change models there, not in the console. - Never expose a private API key to the browser. ``` ## Give the agent a scoped API key [Section titled “Give the agent a scoped API key”](#give-the-agent-a-scoped-api-key) An agent needs a credential to read content or change models. Give it an API key with only the grants the task requires, rather than your own login. * **To read published content**, a public key is enough. It reads published entries and submits forms, and nothing else. * **To read drafts or manage models and entries**, create a private key with the specific `content:*` grants needed. For example, `content:models:read` and `content:models:update` let an agent sync model YAML without touching entries. * **API keys never manage users, roles, API keys, or settings.** Those changes need a person’s login. Put a private key for the CLI in the agent’s environment as `PLENARY_CLI_API_KEY`, and a public key for the site as `PLENARY_API_KEY`. Do not paste it into a prompt or commit it. See [API Keys](/guides/api-keys/) for how to create one and [Permissions](/reference/permissions/) for every grant. ## Let the agent change models with the CLI [Section titled “Let the agent change models with the CLI”](#let-the-agent-change-models-with-the-cli) The [`@plenary/cli`](/reference/cli/) package provides a `plenary` command that changes content models without driving the console. Models live as YAML files in your repository, so every change shows up in a diff you can review. ```sh npm install --save-dev @plenary/cli npx plenary init --base-url https://your-instance.plenarycms.io --site main --locale en-us npx plenary metadata pull # write the instance's models and forms as YAML npx plenary metadata diff # validate the local YAML and print what a push would change npx plenary metadata push # apply it ``` `metadata diff` validates the whole tree and prints a plan without writing anything, so an agent can check its own YAML before applying it. A push never deletes a model unless `--prune` is passed. See [Models as Code](/guides/models-as-code/) for the workflow and [Model YAML](/reference/model-yaml/) for the file format. ## Rules agents commonly get wrong [Section titled “Rules agents commonly get wrong”](#rules-agents-commonly-get-wrong) These Plenary behaviors most often trip up code written from general CMS knowledge. Each links to the page with the detail. 1. **Always send a locale.** Content reads match the locale exactly. A request for a locale with no content returns `404`, or an empty list, rather than falling back to another language. The SDK sends `locale` for you when it is configured. See [Localization](/guides/localization/). 2. **Field values live under `data`.** An entry’s own properties, such as `id`, `slug`, `locale`, `status`, and `published_at`, sit at the top level. The values of the fields you defined are inside `data`. See [Content API](/reference/content-api/). 3. **Public keys see published content only.** If drafts are missing, the key is public, not broken. Draft and preview reads need a private key used only on the server. See [API Keys](/guides/api-keys/). 4. **Page-builder content is a document, not HTML.** A `blocks` field holds a tree of component nodes. Render it with `@plenary/react` and register a React component for every custom block your editors use. See [Page Builder](/guides/page-builder/). 5. **Avoid viewport-height units inside the preview bridge.** Sizing content with `100vh`, `min-h-screen`, `svh`, or `dvh` inside the live-preview frame makes the frame grow without end. See [Live Preview](/guides/live-preview/). 6. **Build your own forms.** Load a form’s definition with `getForm` and send it with `submitForm` from `@plenary/client`. There is no prebuilt form component. Include the anti-spam fields described in [Forms](/guides/forms/). 7. **Use Plenary’s terms.** A visitor’s form record is a **form entry**. An outbound HTTP callback is a **webhook**. Pre-save JavaScript on a model is a **transformer**. Searching the docs for these exact words finds the right page. 8. **Branch on error codes, not messages.** Every error response carries a stable `code`, such as `authentication_required`. See [Errors](/reference/errors/). ## Start a task [Section titled “Start a task”](#start-a-task) A good first prompt names the outcome and points at the docs: ```text Read https://docs.plenarycms.com/llms.txt. Then add a blog to this Next.js app using Plenary: a `post` model in plenary/models/, a list page at /blog and a detail page at /blog/[slug], rendered with @plenary/client. Follow the Blog with Next.js example. ``` The [Examples](/examples/nextjs-blog/) section has complete builds an agent can follow step by step. # Plenary Cloud > Sign up for Plenary Cloud, find your instance URL and console, and learn what Plenary manages for you and where the account portal is. Plenary Cloud is the hosted edition of Plenary. You sign up on plenarycms.com, and Plenary provisions an instance for you: the API, the admin console, media processing, a database, email delivery, and media storage. You build against it exactly as you would against a self-hosted instance. Use Cloud when you want to skip running servers; use [self-hosting](/getting-started/self-hosted/) when you need Plenary on your own infrastructure. ## Sign up [Section titled “Sign up”](#sign-up) Start at [plenarycms.com/signup](https://plenarycms.com/signup). Signup starts a free trial, with no credit card required. The page shows the trial length. The signup wizard has five steps: 1. **Create your account.** Your first and last name, a work email, and a password (at least 8 characters, with an upper-case letter, a lower-case letter, and a digit). Accept the Terms of Service and Privacy Policy. 2. **About your organization.** Your organization name, plus optional industry, team size, and how you heard about Plenary. 3. **Check your email.** Enter the 6-digit code sent to your email address. 4. **Secure your account.** Enter a mobile number and the 6-digit code texted to it. 5. **Set up your first project.** Enter a **Project / site name**, choose **Cloud** under **Deployment**, pick a subdomain, enter your site’s primary domain, and choose a primary use case. Click **Complete setup**. Plenary then provisions your instance and shows its progress. This usually takes under two minutes. When it finishes, click **Open admin dashboard** and sign in with the email and password you chose in step 1. Tip Choosing **Docker / Self-hosted** in step 5 instead issues an evaluation license for running Plenary yourself. See [Self-Hosted Install](/getting-started/self-hosted/). ## Your instance [Section titled “Your instance”](#your-instance) A Cloud **instance** (also called a tenant) is one complete Plenary installation that belongs to your account. Its address comes from the subdomain you chose: | What | URL | | ------------- | ------------------------------------------ | | Instance | `https://.plenarycms.io` | | Admin console | `https://.plenarycms.io/cms` | | API | `https://.plenarycms.io/api/v1` | Subdomains use lowercase letters, numbers, and hyphens, are 1 to 28 characters long, and cannot start or end with a hyphen. Some names are reserved. Your instance starts with: * An admin user with the email and password from signup. It has the `admin` role. * One site, named after your project, with the site key `default`. Pass `site_key=default` (or `siteKey: "default"` in `@plenary/client`) when you read content. Point your code at the instance URL. With `@plenary/client`, that is the `baseUrl`: lib/plenary.ts ```ts import { createClient } from "@plenary/client"; export const plenary = createClient({ baseUrl: "https://your-subdomain.plenarycms.io", apiKey: process.env.PLENARY_API_KEY!, siteKey: "default", locale: "en-us", }); ``` From here, the [Quickstart](/getting-started/quickstart/) walks you through your first model, entry, and API key. ## What Plenary manages for you [Section titled “What Plenary manages for you”](#what-plenary-manages-for-you) On Cloud, Plenary runs the infrastructure, so the console hides the settings that configure it and the API refuses them. Everything else (content models, entries, media, forms, page building, webhooks, transformers, sites, users, roles, API keys, and metrics) works the same as on a self-hosted instance. | Area | Self-hosted | Cloud | | ------------------ | ----------------------------------------------------- | ---------------------------------------------------------------- | | Email sending | You configure a provider under **Global Settings** | Managed. Mail is sent as `PlenaryCMS `. | | SMS sending | You configure a provider under **Global Settings** | Managed | | Media file storage | You choose local disk or S3 under **Global Settings** | Managed | | License | You install one under **Admin Settings → License** | Not used. Your subscription covers the instance. | | Plan and usage | Not applicable | **Admin Settings → Subscription** in the console | The **Global Settings** and **License** pages do not appear in a Cloud console; **Subscription** appears in their place. It shows your plan, its limits, and current usage. If code calls one of the managed settings endpoints on a Cloud instance, the API returns `403` with the error code `cloud_managed`: ```json { "error": { "code": "cloud_managed" } } ``` These endpoints return `cloud_managed` on Cloud: | Method | Path | | ------------ | ------------------------------------- | | `GET`, `PUT` | `/api/v1/settings/email-sending` | | `POST` | `/api/v1/settings/email-sending/test` | | `GET`, `PUT` | `/api/v1/settings/sms-sending` | | `POST` | `/api/v1/settings/sms-sending/test` | | `GET`, `PUT` | `/api/v1/settings/file-storage` | | `GET` | `/api/v1/settings/message-deliveries` | | `GET` | `/api/v1/license` | | `PUT` | `/api/v1/settings/license` | To check which edition an instance runs, call the health endpoint. It needs no authentication: ```bash curl https://your-subdomain.plenarycms.io/api/v1/health ``` ```json { "status": "ok", "database": "ok", "version": "1.0.0", "edition": "cloud" } ``` ## The account portal [Section titled “The account portal”](#the-account-portal) Your Plenary account (the customer account you created at signup) is separate from the user accounts inside your instance. Manage it in the account portal at [plenarycms.com/account](https://plenarycms.com/account): | Page | What you do there | | -------------------------- | ----------------------------------------------------------------------------------------------------------------------- | | **Overview** | See your instances, trial or renewal date, and licenses at a glance. | | **Profile & organization** | Edit your details and your organization, and invite **Team members** who can sign in to the account. | | **Cloud instances** | See each instance’s URL, admin dashboard link, status, version, and plan limits. **Open CMS** takes you to the console. | | **On-prem licenses** | Get license keys for self-hosted deployments. | | **Billing & invoices** | Choose a plan, manage the payment method, and see invoice history. | Signing in to the account portal and signing in to an instance’s console are separate. Your console password starts out the same as the one you chose at signup, but changing one does not change the other. People you add as console users under **Access Management → Users** do not get access to the account portal, and account team members do not automatically get console access. If an instance shows as paused in the portal, set up billing under **Billing & invoices** to resume it. ## Related [Section titled “Related”](#related) * [Quickstart](/getting-started/quickstart/): create a model, publish an entry, and fetch it. * [Settings](/guides/settings/): the settings you still manage on Cloud. * [Users & Permissions](/guides/users-and-permissions/): add your team to the console. * [Self-Hosted Install](/getting-started/self-hosted/): run Plenary on your own infrastructure instead. # Core Concepts > A glossary of the core Plenary concepts, the identifiers each one appears as in JSON, and the guide that covers it. This page defines the terms the rest of the docs use. Each entry gives a short definition, how the concept shows up in API JSON, and where to read more. Identifiers are shown exactly as the API returns them. ## Instance [Section titled “Instance”](#instance) One running Plenary installation: the API, the admin console, media processing, and one MongoDB database. A Cloud instance lives at `https://.plenarycms.io`; a self-hosted one lives wherever you deploy it. On every instance the console is served at `/cms` and the API under `/api/v1`. * **In JSON:** `GET /api/v1/health` reports the instance’s `version` and `edition` (`"on-prem"` or `"cloud"`). * **Read more:** [Plenary Cloud](/getting-started/cloud/), [Self-Hosted Install](/getting-started/self-hosted/). ## Site [Section titled “Site”](#site) A site is one website or app that an instance serves content to. One instance can hold several sites, each with its own locales, timezone, and webhooks. Every content model and form belongs to exactly one site, and so does every entry. A new instance has one site whose key is `default`. * **In JSON:** a site’s identifier is its key, which appears as `site_key` on entries and as the `?site_key=` query parameter on content reads. The site object itself carries it as `key`. * **Read more:** [Sites](/guides/sites/). ## Content model [Section titled “Content model”](#content-model) A content model defines the shape of a kind of content: its name, its fields, the site it belongs to, and settings such as whether it is public. Every model has a `kind`, which cannot be changed after creation: | Kind | Meaning | | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------- | | `collection` | Many entries, each addressed by slug or id. Articles, events, pages. | | `singleton` | Exactly one entry per site and locale, fetched by the model key alone. Site settings, a homepage. | | `form` | A public form. Visitors submit **form entries** to it. Created under **Forms** in the console, not under **Content**. | | `object` | A reusable group of fields embedded in other models through an `object` field. Has no entries of its own. Its key must start with `obj_`. | * **In JSON:** a model is identified by its `key` (lowercase letters, digits, and underscores, starting with a letter, for example `blog_post`) and by a UUID `id`. Entries carry it as `model_key`. A **public** model serves its published entries to public API keys; a **private** model (`"private": true`) is hidden from them. * **Read more:** [Content Models](/guides/content-models/), [Forms](/guides/forms/). ## Field [Section titled “Field”](#field) A field is one named value on a model, such as a title, an image, or a reference to another entry. Each field has a type (`text`, `rich_text`, `number`, `image`, `reference`, `blocks`, and more) plus flags such as required, localized, unique, and private. * **In JSON:** a field is identified by its `key`. An entry’s field values live under `data`, keyed by field key: `"data": { "title": "Hello" }`. In filters you address them as `data.`. * **Read more:** [Fields](/guides/fields/), [Field Types](/reference/field-types/). ## Entry [Section titled “Entry”](#entry) An entry is one piece of content created from a content model: one blog post, one event, the site settings. Every entry belongs to one site and one locale. * **In JSON:** entries have a UUID `id` plus `site_key`, `model_key`, `slug`, `locale`, `title`, `status`, `published_at`, `publish_at`, `unpublish_at`, `created_at`, `updated_at`, `folder_id`, `path`, and `data`. * **Read more:** [Entries & Publishing](/guides/entries-and-publishing/), [Content API](/reference/content-api/). ## Slug [Section titled “Slug”](#slug) The slug is the URL-friendly name of an entry, such as `hello-world`. The console fills it in from the title as you type, and you can edit it. You fetch a collection entry by slug (or by id) at `GET /api/v1/content/{model_key}/{slug}`. Translations of the same entry share a slug and differ by locale. * **In JSON:** `slug` on the entry. * **Read more:** [Entries & Publishing](/guides/entries-and-publishing/). ## Content directory [Section titled “Content directory”](#content-directory) Entries of a collection can be organized into folders. The folder path is separate from the slug, so you route on both together. * **In JSON:** `folder_id` (the containing folder, or `null` at the root) and `path` (the folder’s path, `"/"` at the root). `path` does not include the entry’s own slug. * **Read more:** [Content Directories](/guides/content-directories/). ## Locale [Section titled “Locale”](#locale) A locale is the language and region an entry is written in, such as `en-us` or `fr-ca`. Each site has a default locale and a list of allowed locales. A translation is a separate entry in another locale with the same slug. Reads return only the locale you ask for; there is no automatic fallback to another language. * **In JSON:** `locale` on the entry, and the `?locale=` query parameter on reads. Locales are stored lowercase. * **Read more:** [Localization](/guides/localization/). ## Draft, published, and scheduled [Section titled “Draft, published, and scheduled”](#draft-published-and-scheduled) An entry is either a draft or published. Only published entries are served to public API keys. | State | How it shows in JSON | | ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------ | | Draft | `"status": "draft"` | | Published | `"status": "published"`, with `published_at` set | | Scheduled to publish | `"status": "draft"` with a future `publish_at`. When that time passes, the entry becomes `published`. | | Scheduled to unpublish | `"status": "published"` with a future `unpublish_at`. When that time passes, the entry returns to `draft`. | | Published with changes pending | `"status": "published"` with a `draft` object holding the edited `data` and `slug`. The site keeps serving the live copy until the entry is published again. | A model can be set to **Always published**, in which case every save publishes immediately and there are no drafts. Form entries use a different set of statuses (`new`, `read`, `archived`, `spam`). * **Read more:** [Entries & Publishing](/guides/entries-and-publishing/). ## Blocks field and page document [Section titled “Blocks field and page document”](#blocks-field-and-page-document) A `blocks` field holds a page layout built in the Page Builder. Its value is a **page document**: a JSON tree of component nodes that your front end renders. * **In JSON:** the field value is `{ "version": 1, "root": [ ...nodes ] }`. Each node has an `id`, a `component` key, `props`, and optional named `slots` containing child nodes. * **Read more:** [Page Builder](/guides/page-builder/), [@plenary/react](/sdk/react/). ## Component (block) [Section titled “Component (block)”](#component-block) A component is a building block an editor can place in a `blocks` field: a hero, a card grid, a text block. Plenary includes built-in components (`box`, `section`, `text`, `image`, `video`); you register your own React components in your site with `@plenary/react`, declaring their props and slots. The Page Builder reads that registration from your running site, so editors only see components your code can render. * **In JSON:** a node’s `component` value is the registered component key, for example `"component": "hero"`. * **Read more:** [Page Builder](/guides/page-builder/), [Page Builder Site example](/examples/page-builder-site/). ## Media asset [Section titled “Media asset”](#media-asset) A media asset is an uploaded image, video, or file in the Media Library. Image fields store a reference to an asset, plus per-use details such as alt text and a focal point. Plenary generates image variants (resized and cropped copies) for you. * **In JSON:** assets are identified by a UUID `media_id`. An image field value looks like `{ "media_id": "…", "alt": "…" }`. Asset URLs are paths on the instance, such as `/media/{media_id}/original.jpg`. * **Read more:** [Media Library](/guides/media-library/). ## API key [Section titled “API key”](#api-key) An API key lets code, rather than a person, call the API. Send it in the `X-API-KEY` header. There are two types: | Type | Token prefix | What it can do | | ------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | | Public | `pln_pub_` | Read published entries of public models on its one site, read form definitions, and submit form entries. Safe to ship in a browser or mobile app. | | Private | `pln_prv_` | Whatever its own grants allow, limited to content capabilities and, usually, to one site. Keep it on a server. | API keys can never manage users, roles, keys, or settings. * **In JSON:** a key has a UUID `id`, a `key_type` of `public` or `private`, the `site_key` it belongs to (empty for an instance-wide private key), and (for private keys) `grants`. * **Read more:** [API Keys](/guides/api-keys/), [Authentication](/reference/authentication/). ## Role and grant [Section titled “Role and grant”](#role-and-grant) People sign in to the console as **users**. A **super user** can do everything, including managing users, roles, sites, and instance settings. Everyone else gets access from a **role on each site**: a role belongs to one site and is a named set of **grants**, each pairing a capability, such as `content:entries:publish`, with an optional content model that narrows it. Access is allow-only: a user can do exactly what their roles allow on each site and nothing else. Every site starts with the roles `admin`, `developer`, `editor`, and `reviewer`. * **In JSON:** a grant is `{ "key": "content:entries:update", "site_key": "default", "content_model_key": "blog_post" }`, where `content_model_key` is optional and a role’s grants take the role’s site. A user carries `is_super_user` and `site_roles`, a list of `{ "site_key", "role_key" }`. * **Read more:** [Users & Permissions](/guides/users-and-permissions/), [Permissions reference](/reference/permissions/). ## Webhook [Section titled “Webhook”](#webhook) A webhook is an outbound HTTP POST that Plenary sends to a URL you choose after something happens, such as an entry being published. Webhooks are configured on a content model, a form, or a whole site. They run after the change is saved and cannot alter it. A common use is telling your site to revalidate its cache. * **In JSON:** the payload’s `event` is one of `entry.created`, `entry.updated`, `entry.published`, `entry.unpublished`, `entry.deleted`, or `form.submitted` (`webhook.test` for the console’s test button). * **Read more:** [Webhooks](/guides/webhooks/), [Webhook Events](/reference/webhook-events/), [Instant Revalidation](/examples/revalidation/). ## Transformer [Section titled “Transformer”](#transformer) A transformer is a short JavaScript function attached to a content model that runs on every create and update of an entry, before validation. It can change the data being saved or refuse the save. Transformers do not run on form entries. * **In JSON:** a model’s transformers are a list of objects with `id`, `name`, `source`, and `active`. * **Read more:** [Transformers](/guides/transformers/). ## Revision [Section titled “Revision”](#revision) A revision is a recorded snapshot of an entry or model after a change, with who made it and when. Revisions power the **History** tab in the console. You can restore an entry to an earlier revision. Revision tracking is on by default and can be turned off per model. * **In JSON:** a revision has an `id`, a `target_type` (`entry` or `model`), a `target_id`, an `action` such as `publish`, and an `actor`. * **Read more:** [Entries & Publishing](/guides/entries-and-publishing/). # Introduction > What Plenary is, who it is for, the pieces that make it up, and how these docs are organized. Plenary is a hybrid CMS. Editors manage structured content and design pages visually in a web console; your own front end fetches that content over an HTTP API and renders it. Plenary never renders your public site. It stores and serves content, and your Next.js app (or any other HTTP client) turns it into pages. ## What “hybrid” means here [Section titled “What “hybrid” means here”](#what-hybrid-means-here) Plenary combines two ways of working with content in one system: * **Headless content.** You define content models (an Article, an Event, a Site Settings singleton), editors fill them in, and your code reads published entries as JSON from the [Content API](/reference/content-api/). * **Visual page building.** A content model can include a `blocks` field. Editors compose that field from components in the [Page Builder](/guides/page-builder/), which shows a live preview of *your* site while they work. The stored value is a JSON component tree that your front end renders with your own React components. Both live side by side. A model can hold plain fields, a `blocks` field, or both, and they are all read through the same API. ## Who it is for [Section titled “Who it is for”](#who-it-is-for) * **Developers** who want content in a typed JSON API, with the rendering, routing, and hosting of the site left entirely to them. * **Editors and marketers** who need to write, schedule, translate, and lay out pages without a deploy. * **AI coding agents** working for either of the above. These docs are written so an agent can follow them literally; see [Building with AI Agents](/getting-started/ai-agents/). ## The pieces [Section titled “The pieces”](#the-pieces) | Piece | What it is | Where it lives | | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------- | | **Instance** | One running Plenary installation: the API, the console, media processing, and a MongoDB database. | Plenary Cloud, or your own infrastructure | | **Console** | The admin web app where editors and admins manage models, entries, media, forms, users, and settings. | `https://your-instance/cms` | | **API** | The HTTP API your site and tools call. Content reads use a public API key in the `X-API-KEY` header. | `https://your-instance/api/v1` | | **SDK** | TypeScript packages for consuming Plenary: `@plenary/client` (fetching content and submitting forms), `@plenary/react` (rendering Page Builder content), `@plenary/next` (Next.js caching and revalidation), and `@plenary/core` (shared types). | npm, version 1.0.x | | **CLI** | `@plenary/cli`, the `plenary` command: syncs model YAML, manages entries and media, and calls any API endpoint from a terminal or CI. | npm, version 1.0.x | Start with the [SDK overview](/sdk/overview/) to see how the packages fit together, and the [CLI reference](/reference/cli/) for the command line. ## Cloud or self-hosted [Section titled “Cloud or self-hosted”](#cloud-or-self-hosted) You can run Plenary two ways. The product is the same; the difference is who runs the infrastructure. * **[Plenary Cloud](/getting-started/cloud/).** Sign up at plenarycms.com and get an instance at `https://.plenarycms.io`. Plenary runs the servers, database, email delivery, and media storage. * **[Self-hosted](/getting-started/self-hosted/).** Run the Plenary Docker image on your own infrastructure with your own MongoDB. You configure email, SMS, and media storage yourself, and install a [license](/reference/licensing/). Everything you build against an instance (models, entries, API keys, SDK code) works the same on both. ## How these docs are organized [Section titled “How these docs are organized”](#how-these-docs-are-organized) | Section | Use it when you want to | | ------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------- | | **Getting Started** | Understand Plenary and get your first content on screen. Read [Core Concepts](/getting-started/concepts/) and the [Quickstart](/getting-started/quickstart/) first. | | **Guides** | Learn one feature end to end, with the console steps and the API/SDK way side by side. | | **Examples** | Copy a complete, working build, such as a [Next.js blog](/examples/nextjs-blog/) or a [contact form](/examples/contact-form/). | | **Reference** | Look up an exact endpoint, parameter, field type, error code, or permission. | | **SDK** | Look up every export and signature of the `@plenary/*` packages. | ## Using an AI coding agent [Section titled “Using an AI coding agent”](#using-an-ai-coding-agent) If you are building with an AI coding agent, point it at [`/llms.txt`](/llms.txt) (an index of every page) or [`/llms-full.txt`](/llms-full.txt) (the full docs in one file), and read [Building with AI Agents](/getting-started/ai-agents/) for setup and prompting advice. ## Next steps [Section titled “Next steps”](#next-steps) * [Core Concepts](/getting-started/concepts/): the vocabulary every other page uses. * [Quickstart](/getting-started/quickstart/): create a model, publish an entry, and fetch it from Next.js. # Quickstart > Go from an empty Plenary instance to published content rendered in a Next.js App Router app, using the console, curl, and @plenary/client. 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”](#prerequisites) * 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`. ## 1. Get an instance [Section titled “1. Get an instance”](#1-get-an-instance) Pick one: * **Plenary Cloud.** Start a free trial at [plenarycms.com/signup](https://plenarycms.com/signup). When provisioning finishes you get an instance at `https://.plenarycms.io` and can sign in to its console at `https://.plenarycms.io/cms` with the email and password you chose. Details: [Plenary Cloud](/getting-started/cloud/). * **Self-hosted.** Run the Plenary Docker image with MongoDB and create the first admin user. Details: [Self-Hosted Install](/getting-started/self-hosted/). 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”](#2-create-a-content-model) 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. Note Model keys and both model names must be unique within the site. If you see “A model with this key already exists”, pick a different name and key, and use that key in place of `post` for the rest of this page. ## 3. Add and publish an entry [Section titled “3. Add and publish an entry”](#3-add-and-publish-an-entry) 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. ## 4. Create a public API key [Section titled “4. Create a public API key”](#4-create-a-public-api-key) 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. ## 5. Fetch the entry with curl [Section titled “5. Fetch the entry with curl”](#5-fetch-the-entry-with-curl) Put the values in your shell, then list the model’s published entries: ```bash 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: ```json [ { "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: ```bash 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](/reference/errors/) for every error code. ## 6. Render it in Next.js [Section titled “6. Render it in Next.js”](#6-render-it-in-nextjs) Create a Next.js app with the App Router and TypeScript, then add the Plenary client: ```bash 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 ```bash 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 ```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 ```tsx import Link from "next/link"; import { plenary, type Post } from "@/lib/plenary"; export default async function Home() { const { items } = await plenary.listEntries("post", { sort: { published_at: "desc" }, }); return (

Posts

    {items.map((post) => (
  • {post.data.title}
  • ))}
); } ``` 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 ```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", slug); return (

{post.data.title}

{post.data.body}

); } catch (err) { if (err instanceof PlenaryNotFoundError) notFound(); throw err; } } ``` Start the dev server: ```bash 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. Note `next dev` fetches on every request. In a production build (`next build`), Next.js prerenders the home page once at build time, so new entries do not appear until you rebuild or revalidate. [Instant Revalidation](/examples/revalidation/) shows how to refresh pages the moment an editor publishes. ## What you built [Section titled “What you built”](#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”](#next-steps) * [Blog with Next.js](/examples/nextjs-blog/): a fuller blog with images, references, and metadata. * [Fields](/guides/fields/): every field type you can add to a model. * [Content API](/reference/content-api/): filtering, sorting, pagination, and locales. * [@plenary/client](/sdk/client/): every client method and option. * [Page Builder](/guides/page-builder/): let editors lay out pages visually with your own components. # Self-Hosted Install > Run Plenary on your own infrastructure as a single Docker container with MongoDB, including configuration, secrets, volumes, first-boot admin setup, licensing, upgrades, and backups. A self-hosted Plenary installation is one Docker container plus a MongoDB database that you run. The container holds everything else: the API, the admin console, the media worker, and a web server. Use this when you need Plenary on your own infrastructure; if you would rather not run servers, use [Plenary Cloud](/getting-started/cloud/). ## What is in the image [Section titled “What is in the image”](#what-is-in-the-image) The Plenary image runs four things in one container: | Process | Role | | ---------- | ----------------------------------------------------------------------- | | `plenaryd` | The API server. Listens on port `8080` inside the container. | | `artifexd` | The media worker. Generates image variants and video posters. | | Console | The admin web app, served as static files. | | Caddy | The web server. Listens on port `80` and routes requests to the others. | Caddy routes requests on port `80` like this: | Path | Goes to | | ------------------- | ------------------------------------------------------------- | | `/` | Redirects to `/cms` | | `/cms` and below | The admin console | | `/api/` and below | `plenaryd` | | `/media/` and below | Media files on disk, or `plenaryd` when a file is not on disk | The container serves plain HTTP. Put it behind your own reverse proxy or load balancer to terminate TLS. The container’s entrypoint starts all processes and exits as soon as any one of them exits. It does not restart them itself, so run the container with a restart policy (`restart: unless-stopped` in Docker Compose, or your orchestrator’s equivalent). ## Requirements [Section titled “Requirements”](#requirements) * A Docker host (or any container platform, such as ECS or Kubernetes). * MongoDB, reachable from the container. A standalone server works; a replica set is not required. * A hostname for the instance, such as `cms.example.com`, and a reverse proxy or load balancer that terminates TLS for it. * Optionally, a Plenary license bound to that hostname. Without one the instance runs on the Free plan: one site, no forms, no single sign-on, no GraphQL API. See [Licensing](#licensing). ## Get the image [Section titled “Get the image”](#get-the-image) Plenary is published to a public registry for `linux/amd64` and `linux/arm64`. No login is needed to pull: ```bash docker pull public.ecr.aws/plenarycms/plenary:v1.5.2 ``` Every release has an immutable tag, `v` followed by its version. The major version is also a moving tag (`public.ecr.aws/plenarycms/plenary:1`) that follows the newest compatible release. There is no `latest` tag: a licensed instance that pulled a release newer than its license’s update window would drop to the Free plan, so pin a version and upgrade deliberately. The examples on this page use `v1.5.2`; replace it with the release you are installing. ## Configuration file [Section titled “Configuration file”](#configuration-file) Plenary reads one YAML file. Inside the container its default path is `/etc/plenary/plenary.yaml`; set the `PLENARY_CONFIG` environment variable to use a different path. Both `plenaryd` and `artifexd` read the same file. Any `${VAR_NAME}` in the file is replaced with that environment variable’s value when the file is loaded. If a referenced variable is not set, Plenary refuses to start and names the missing variables. Use this to keep the database password out of the file. A complete starting configuration: plenary/plenary.yaml ```yaml server: bind_address: "0.0.0.0" port: 8080 public_url: "https://cms.example.com" mongodb: url: "${PLENARY_MONGODB_URL}" auth: jwt: issuer: "plenary" secrets: encryption_key_file: "/etc/plenary/secrets/encryption_key" jwt_signing_key_file: "/etc/plenary/secrets/jwt_signing_key" license: file: "/etc/plenary/secrets/license" storage: local_data_dir: "/var/lib/plenary" temp_dir: "/tmp/plenary" bootstrap: setup_token_file: "/etc/plenary/secrets/setup_token" allow_initial_setup: false locale: default: "en-us" timezone: "UTC" logging: level: "info" format: "json" ``` The settings you are most likely to change: | Key | Default | What it does | | --------------------------------- | ---------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | | `server.public_url` | none | The public URL of the instance, without a trailing slash. Used for token audiences, CORS for the console, and license host matching. **Required.** | | `server.bind_address` | `0.0.0.0` | Address `plenaryd` listens on inside the container. | | `server.port` | `8080` | Port `plenaryd` listens on inside the container. Keep `8080`: the bundled Caddy forwards `/api/` to `localhost:8080`. | | `mongodb.url` | none | MongoDB connection string. The database name is the URL path; with no path, Plenary uses the database `plenary`. | | `auth.jwt.issuer` | none | Issuer name stamped into console session tokens. | | `auth.jwt.access_token_ttl` | `15m` | Lifetime of a console access token. | | `auth.jwt.refresh_token_ttl` | `720h` (30 days) | Lifetime of a console refresh token. | | `secrets.encryption_key_file` | none | Path to the encryption key. See [Secrets](#secrets). **Required.** | | `secrets.jwt_signing_key_file` | none | Path to the session signing key. **Required.** | | `license.file` | none | Path to a license file. See [Licensing](#licensing). | | `storage.local_data_dir` | none | Where uploaded media is stored when media uses local storage. Keep `/var/lib/plenary`: that is the directory the bundled Caddy serves `/media/` files from. | | `storage.temp_dir` | none | Scratch space for uploads and processing. | | `bootstrap.setup_token_file` | none | Path to the one-time token that authorizes [creating the first admin](#first-boot-create-the-admin-user). | | `locale.default` | none | Default locale for new sites, such as `en-us`. | | `locale.timezone` | none | Default IANA timezone for new sites, such as `UTC` or `America/Denver`. | | `logging.level` | `info` | `debug`, `info`, `warn`, or `error`. | | `logging.format` | `text` | `json` or `text`. | | `content.schedule_sweep_interval` | `1m` | How often scheduled publish and unpublish times are checked. | | `webhooks.delivery` | `concurrent` | `concurrent`, or `ordered` to deliver webhooks one at a time, oldest first. | | `webhooks.delivery_retention` | `720h` (30 days) | How long webhook delivery records are kept. `0` keeps them forever. | | `error_reporting.sentry_dsn` | none | Send errors to a Sentry project. Leave unset to turn off. | Email sending, SMS sending, and media storage (local disk or Amazon S3) are not configured in this file. An admin sets them in the console under **Admin Settings → Global Settings** after first boot. See [Settings](/guides/settings/). ## Secrets [Section titled “Secrets”](#secrets) Plenary needs two key files before it starts. Both `plenaryd` and `artifexd` exit at startup if either file is missing. | File | Used for | If you lose it | | ------------------------------------------------ | --------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------ | | Encryption key (`secrets.encryption_key_file`) | Encrypting credentials stored in the database, such as email, SMS, and S3 credentials entered in **Global Settings**. | Those stored credentials cannot be decrypted. You must enter them again. | | JWT signing key (`secrets.jwt_signing_key_file`) | Signing console session tokens. | Everyone is signed out. Nothing else is lost. | Each key is 32 random bytes. Generate them, together with a setup token for first boot, in a `plenary/secrets` directory next to your Compose file: ```bash mkdir -p plenary/secrets head -c 32 /dev/urandom > plenary/secrets/encryption_key head -c 32 /dev/urandom > plenary/secrets/jwt_signing_key openssl rand -hex 24 > plenary/secrets/setup_token ``` The container runs as the user `plenary` (uid `100`, gid `101`), which must be able to read the configuration and secrets: ```bash sudo chown -R 100:101 plenary sudo chmod 700 plenary/secrets sudo chmod 600 plenary/secrets/* ``` Back up the encryption key somewhere safe and separate from the database. Never commit these files to source control. ## Volumes [Section titled “Volumes”](#volumes) Mount two locations: | Container path | Contents | Persist it? | | ------------------ | ---------------------------------------------------------------------- | ---------------- | | `/etc/plenary` | `plenary.yaml` and the `secrets/` directory. Can be mounted read-only. | Yes. Back it up. | | `/var/lib/plenary` | Uploaded media and generated variants, when media uses local storage. | Yes. Back it up. | If you switch media storage to Amazon S3 in **Global Settings**, new uploads go to your bucket instead, but keep the volume for anything already stored on disk. ## Run with Docker Compose [Section titled “Run with Docker Compose”](#run-with-docker-compose) This Compose file runs MongoDB and Plenary together and publishes Plenary on port `8080` of the host’s loopback interface, for a reverse proxy on the same host to forward to: docker-compose.yml ```yaml services: mongo: image: mongo:8 restart: unless-stopped volumes: - mongo-data:/data/db plenary: image: public.ecr.aws/plenarycms/plenary:v1.5.2 restart: unless-stopped depends_on: - mongo ports: - "127.0.0.1:8080:80" environment: PLENARY_MONGODB_URL: "mongodb://mongo:27017/plenary" volumes: - ./plenary:/etc/plenary:ro - plenary-media:/var/lib/plenary volumes: mongo-data: plenary-media: ``` Your directory should look like this: ```text . ├── docker-compose.yml └── plenary ├── plenary.yaml └── secrets ├── encryption_key ├── jwt_signing_key ├── license └── setup_token ``` Start it and check that it is healthy: ```bash docker compose up -d curl http://127.0.0.1:8080/api/v1/health ``` ```json { "status": "ok", "database": "ok", "version": "1.3.0", "edition": "on-prem", "license": "ok", "tier": "full" } ``` `status` is `ok` when the database answers, and `degraded` (with HTTP `503`) when it does not. `license` reports the license state and `tier` whether the instance is on the Free plan (`free`) or licensed (`full`); neither affects the HTTP status. Use this endpoint for your load balancer’s health check. Then point your reverse proxy at `127.0.0.1:8080` for your hostname, terminating TLS. ## Licensing [Section titled “Licensing”](#licensing) A self-hosted instance runs without a license on the **Free plan**: one site, no forms, and no single sign-on. Everything else, including creating as many users as you need, works. A license lifts the three limits. See [The Free plan](/reference/licensing/#the-free-plan) for exactly what is refused and how. Get a license: * **Evaluation.** Sign up at [plenarycms.com/signup](https://plenarycms.com/signup) and choose **Docker / Self-hosted** in the last step. You enter the hostname the instance will run at, and receive an evaluation license key. * **Purchased.** From **On-prem licenses** in the account portal at [plenarycms.com/account](https://plenarycms.com/account). A license is bound to one or more hostnames. Plenary compares them with the host in `server.public_url`. A license for `cms.example.com` only works when `public_url` is `https://cms.example.com`. One wildcard label is allowed, such as `*.staging.example.com`. Plenary looks for the license in three places, in this order, and uses the first one it finds: 1. The `PLENARY_LICENSE` environment variable, containing the license key itself. 2. The file at `license.file` in the configuration. 3. A license an admin installed in the console under **Admin Settings → License**. Sources 1 and 2 are read at startup, so changing them requires a restart. A license installed in the console takes effect immediately. A new install can start on the Free plan and have its license installed in the console once the admin signs in, or carry it from the first boot through the environment variable or the file. When `public_url` points at `localhost` or `127.0.0.1`, the license is not enforced, so you can try Plenary locally without one. See [Licensing](/reference/licensing/) for license states, error codes, and update windows. ## First boot: create the admin user [Section titled “First boot: create the admin user”](#first-boot-create-the-admin-user) A new instance has no users. Create the first admin, and the first site, with one call to the bootstrap endpoint. It is authorized by the setup token from `bootstrap.setup_token_file`, sent in the `X-Setup-Token` header, and it works only once: after any user exists it returns `409`. ```bash curl -X POST https://cms.example.com/api/v1/setup/bootstrap \ -H "Content-Type: application/json" \ -H "X-Setup-Token: $(cat plenary/secrets/setup_token)" \ -d '{ "admin": { "email": "you@example.com", "password": "Choose-a-strong-passw0rd", "first_name": "Ada", "last_name": "Lovelace" }, "site": { "name": "My Site" } }' ``` ```json { "status": "ok" } ``` This creates: * An admin user with the `admin` role. Their username is derived from the email address (`you` for `you@example.com`); they can sign in with either. * A site named **My Site** with the site key `default`, using `locale.default` and `locale.timezone` from the configuration. | Field | Required | Notes | | -------------------- | -------- | ----------------------------------------------------------------------------------- | | `admin.email` | Yes | The admin’s email address. | | `admin.password` | Yes | At least 8 characters, with an upper-case letter, a lower-case letter, and a digit. | | `admin.first_name` | No | | | `admin.last_name` | No | | | `admin.display_name` | No | Defaults to a name derived from first and last name. | | `site.name` | Yes | Display name of the first site. | Errors from this endpoint: | Status | Code | Meaning | | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------- | | `403` | `invalid_setup_token` | The `X-Setup-Token` header does not match the token file. | | `404` | `not_found` | The token file named by `bootstrap.setup_token_file` is missing or empty. | | `409` | `already_bootstrapped` | A user already exists. | | `422` | `invalid_email`, `password_too_short`, `password_missing_uppercase`, `password_missing_lowercase`, `password_missing_digit`, `site_name_required` | The request body is invalid. | Now sign in to the console at `https://cms.example.com/cms`. Then: 1. Delete `plenary/secrets/setup_token`. With the file gone, the bootstrap endpoint answers `404`. 2. Open **Admin Settings → Global Settings** and configure email sending, so Plenary can send invitations and password resets. Set up SMS and S3 media storage there too if you need them. 3. Follow the [Quickstart](/getting-started/quickstart/) from step 2 to create your first model. ## Upgrades [Section titled “Upgrades”](#upgrades) To upgrade, back up first (see [Backups](#backups)), then run the new image and recreate the container: ```bash docker compose pull # or load the new image another way docker compose up -d ``` Plenary applies any database changes a release needs automatically when it starts. Each change runs once and is recorded in the database. There is no separate migration step. A license can limit which releases it covers. If you start a release newer than your license allows, the instance runs on the Free plan and `/api/v1/health` reports `"license": "update_window_exceeded", "tier": "free"`. Go back to the previous image, or install a renewed license. Pinning the `vX.Y.Z` tag rather than the moving major tag keeps this from happening by surprise. See [Licensing](/reference/licensing/). ## Backups [Section titled “Backups”](#backups) Back up three things, ideally at the same time: | What | How | | ------------------------- | ---------------------------------------------------------------------------------------------------------------------------- | | The MongoDB database | `mongodump`, or your MongoDB host’s snapshot feature. All content, models, users, settings, and revision history live here. | | Media files | The volume mounted at `/var/lib/plenary`, if media uses local storage. If it uses S3, back up the bucket instead. | | Configuration and secrets | The directory mounted at `/etc/plenary`. Without the encryption key, credentials stored in the database cannot be decrypted. | For example, with the Compose file above: ```bash docker compose exec -T mongo mongodump --archive --db plenary > plenary-$(date +%F).archive ``` To restore, restore the database, the media volume, and the configuration directory from the same backup, then start the container. ## Related [Section titled “Related”](#related) * [Settings](/guides/settings/): email, SMS, and media storage. * [Licensing](/reference/licensing/): license states and installation. * [Users & Permissions](/guides/users-and-permissions/): invite your team. * [Plenary Cloud](/getting-started/cloud/): the managed alternative. # Contact Form > Build a Next.js App Router contact page that loads a Plenary form's definition in the browser, submits it with the public key, shows per-field errors, and includes the anti-spam fields. This example builds a `/contact` page in a Next.js App Router site. The browser reads the form’s definition from Plenary with `getForm`, renders an input for each field, and submits with `submitForm` using your public API key. It shows Plenary’s per-field validation errors next to the right input and includes both anti-spam fields. Because the markup is generated from the definition, adding or changing a field in the console changes the form on your site with no code change. Submitting from the browser is the recommended pattern for public forms: * **Each visitor has their own rate limit.** Plenary allows 10 submits per minute per form, per client IP. A browser submit counts against the visitor’s IP; a submit from your server would count every visitor against your server’s single IP. * **Entries record the visitor.** Each entry’s `source` holds the visitor’s IP address and user agent, not your server’s. * **The page stays cacheable.** The definition, with its fresh anti-spam `ts` token, is read when the form loads in the browser, so the page itself can be statically generated or served from a CDN. The trade-off is that the form needs JavaScript. A public key is designed for browser code: it can read form definitions and submit forms, and nothing else. ## Prerequisites [Section titled “Prerequisites”](#prerequisites) * Node.js 20 or later and a Next.js 16 App Router project with TypeScript and the default `@/*` import alias (`npx create-next-app@latest` sets this up). * `@plenary/client` 1.0.x: `npm install @plenary/client`. * A Plenary instance, and a **public API key** assigned to your site (**Access Management → API Keys**). Set its **Allowed origins** to your site’s origins (for example `https://www.example.com` and `http://localhost:3000`) so other sites cannot borrow your quota. See [API keys](/guides/api-keys/#restrictions). * A form with the key `contact`, active and assigned to your site. Create it under **Forms → New form** with these fields, then **Save form**: | Key | Name | Type | Required | Settings | | --------- | ------- | -------- | -------- | -------------------------------------------------------------------- | | `name` | Name | `text` | yes | Validation `max_length` 80 | | `email` | Email | `email` | yes | | | `topic` | Topic | `select` | no | Options `Sales` / `sales`, `Support` / `support` | | `message` | Message | `text` | yes | UI control `textarea`; validation `min_length` 10, `max_length` 2000 | The code handles any [form field type](/guides/forms/#field-types-a-form-can-use) except `object`, `list`, and `json`, so you can add fields later without editing it. ## Environment variables [Section titled “Environment variables”](#environment-variables) .env.local ```bash # Your instance's origin, without /api/v1. Placeholder: replace with your host. NEXT_PUBLIC_PLENARY_BASE_URL=https://your-instance.plenarycms.io # The public API key (starts with pln_pub_). Safe in the browser. NEXT_PUBLIC_PLENARY_PUBLIC_KEY=pln_pub_YOUR_PUBLIC_KEY # The key of the site the form belongs to. NEXT_PUBLIC_PLENARY_SITE_KEY=default ``` The `NEXT_PUBLIC_` prefix makes Next.js include these values in the browser bundle, at build time. Only ever do that with a **public** key; a private key must never have this prefix. ## Files [Section titled “Files”](#files) ```text lib/plenary-browser.ts Plenary client for browser code, and the form key app/contact/fields.ts Helpers: reading field settings, converting values, error messages app/contact/ContactForm.tsx Client Component: loads the definition, renders fields, submits app/contact/page.tsx The page, statically generated ``` ### The client [Section titled “The client”](#the-client) lib/plenary-browser.ts ```ts import { createClient } from "@plenary/client"; /** The key of the form in Plenary (Forms → your form → Settings → Key). */ export const CONTACT_FORM_KEY = "contact"; /** * A Plenary client for browser code, using the public key. Next.js inlines * NEXT_PUBLIC_ variables at build time, so they must be referenced literally. */ export const plenaryBrowser = createClient({ baseUrl: process.env.NEXT_PUBLIC_PLENARY_BASE_URL!, apiKey: process.env.NEXT_PUBLIC_PLENARY_PUBLIC_KEY!, siteKey: process.env.NEXT_PUBLIC_PLENARY_SITE_KEY!, locale: "en-us", }); ``` ### Helpers [Section titled “Helpers”](#helpers) Real inputs are named `field.` so that a form field can never collide with the reserved `website` and `ts` names, even if your form defines its own `website` field. `readValue` converts each field’s `FormData` entries to the JSON type the field expects. `fieldMessage` turns one of Plenary’s field error codes into a readable message. app/contact/fields.ts ```ts import type { PublicFormField } from "@plenary/client"; /** Inputs are named `field.` so a form field can never collide with `website` or `ts`. */ export const FIELD_PREFIX = "field."; export interface SelectOption { label: string; value: string; } /** The options of a select or multi_select field, from `settings.options`. */ export function optionsOf(field: PublicFormField): SelectOption[] { const options = field.settings?.options; if (!Array.isArray(options)) return []; return options.filter( (o): o is SelectOption => typeof o === "object" && o !== null && typeof (o as SelectOption).label === "string" && typeof (o as SelectOption).value === "string", ); } /** Reads a string from `ui`, e.g. `placeholder`, `control`, `help_text`. */ export function uiString(field: PublicFormField, name: string): string | undefined { const value = field.ui?.[name]; return typeof value === "string" ? value : undefined; } /** Reads a number from `validation`, e.g. `min_length`, `max_length`, `min_val`. */ export function ruleNumber(field: PublicFormField, name: string): number | undefined { const value = field.validation?.[name]; return typeof value === "number" ? value : undefined; } /** Turns one field's FormData entries into the JSON value Plenary expects, or undefined for "not answered". */ export function readValue(field: PublicFormField, formData: FormData): unknown { const raw = formData .getAll(FIELD_PREFIX + field.key) .filter((v): v is string => typeof v === "string"); const first = raw[0] ?? ""; switch (field.type) { case "boolean": return raw.length > 0; case "number": return first === "" ? undefined : Number(first); case "multi_select": return raw.length > 0 ? raw : undefined; case "tags": { const tags = first .split(",") .map((t) => t.trim()) .filter((t) => t !== ""); return tags.length > 0 ? tags : undefined; } case "object": case "list": case "json": // This example does not render structured fields. return undefined; default: return first === "" ? undefined : first; } } /** A readable message for one of Plenary's field error codes. */ export function fieldMessage(code: string, vars: Record): string { switch (code) { case "entry_field_required": case "entry_field_required_nonempty": case "entry_field_value_required": return "This field is required."; case "entry_field_value_taken": return "This value has already been used."; case "entry_field_rule_violation": if (vars.rule === "min_length") return `Use at least ${vars.min_length} characters.`; if (vars.rule === "max_length") return `Use at most ${vars.max_length} characters.`; return "This value is not in the expected format."; default: return "This value is not valid."; } } ``` ### The form [Section titled “The form”](#the-form) The component loads the definition when it mounts, then submits with `submitForm`, passing the honeypot and the `ts` token as options. A `PlenaryError` becomes either a per-field message (when `vars.field` names a field) or a form-level message. The inputs are uncontrolled, so a failed attempt keeps what the visitor typed. app/contact/ContactForm.tsx ```tsx "use client"; import { useEffect, useState } from "react"; import { PlenaryError, type PublicFormDefinition, type PublicFormField } from "@plenary/client"; import { plenaryBrowser, CONTACT_FORM_KEY } from "@/lib/plenary-browser"; import { FIELD_PREFIX, fieldMessage, optionsOf, readValue, ruleNumber, uiString } from "./fields"; type Status = "loading" | "unavailable" | "ready" | "sending" | "sent"; const INPUT_TYPES: Record = { email: "email", url: "url", phone: "tel", number: "number", date: "date", time: "time", color: "color", }; /** Off-screen rather than display:none, so simple bots still see and fill it. */ const honeypotStyle: React.CSSProperties = { position: "absolute", left: "-10000px", width: "1px", height: "1px", overflow: "hidden", }; function FieldInput({ field }: { field: PublicFormField }) { const name = FIELD_PREFIX + field.key; const id = `contact-${field.key}`; const placeholder = uiString(field, "placeholder"); switch (field.type) { case "boolean": return ; case "select": { const options = optionsOf(field); if (uiString(field, "control") === "radio") { return ( {options.map((o) => ( ))} ); } return ( ); } case "multi_select": return ( {optionsOf(field).map((o) => ( ))} ); case "text": if (uiString(field, "control") === "textarea") { return (