Skip to content

Core Concepts

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.

One running Plenary installation: the API, the admin console, media processing, and one MongoDB database. A Cloud instance lives at https://<subdomain>.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.

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.

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, Forms.

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.<key>.
  • Read more: Fields, Field Types.

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, Content API.

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.

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.

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.

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).

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, @plenary/react.

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.

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.

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, Authentication.

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, Permissions reference.

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, Webhook Events, Instant Revalidation.

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.

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.