Skip to content

Sites

A site is one website or app that an instance serves content to. One Plenary instance can hold several sites, such as a marketing site, a docs site, and a mobile app, or one site per brand or region. Every entry belongs to exactly one site, each site has its own locales and timezone, and API keys can be limited to specific sites. A new instance starts with one site whose key is default.

{
"key": "default",
"name": "Rocky Mountain Synod",
"is_active": true,
"default_locale": "en-us",
"locales": ["en-us", "es-mx"],
"timezone": "America/Denver",
"config": {},
"created_at": "2026-06-26T00:00:00Z"
}
Property Type Meaning
key string Permanent identifier. Lowercase letters, digits, and underscores, starting with a letter. Appears as site_key on entries and in ?site_key=.
name string Display name, shown in the console’s site switcher.
description string or null Optional.
is_active boolean Whether the site is active. See Deactivate a site.
default_locale string The locale used when a read or write does not name one. Must be in locales.
locales array of strings The locales content may be written in. See Localization.
timezone string IANA timezone such as Europe/Berlin. Used for schedule inputs and stats.
config object Free-form JSON stored with the site.

Sites live under Admin Settings → Site Management. Only a super user can create or delete a site; editing a site’s settings needs admin:sites:update on that site, which its Admin role has.

  • Create: select New in the Sites rail. Enter a Name and Key, then Create site. The key cannot be changed later.
  • Edit: select a site to change its Name, Timezone, Locales (with Add locale and Make default), and active state, then save.
  • Webhooks: each site has its own webhooks. See Site webhooks.
  • Delete: select Delete site and type the key to confirm.

Everyone working in the console picks a site from the console’s site switcher. The Content catalog, entry lists, and dashboards show the selected site.

Site management is an administrative task, so it needs a signed-in user’s token rather than an API key.

Method Path Permission Notes
GET /api/v1/sites any signed-in user or private key Lists every site. Public keys get 403.
POST /api/v1/sites Super user Body: key, name, and optional description, is_active, default_locale, locales, timezone, config.
PUT /api/v1/sites/{site_key} admin:sites:update Body: name (required) and the fields to change.
DELETE /api/v1/sites/{site_key}?confirm_key={site_key} Super user Add &purge_content=true if the site has entries.
Terminal window
curl -X POST "https://your-instance.plenarycms.io/api/v1/sites" \
-H "Authorization: Bearer $PLENARY_ACCESS_TOKEN" \
-H "Content-Type: application/json" \
-d '{
"key": "app",
"name": "Mobile App",
"default_locale": "en-us",
"locales": ["en-us", "fr-ca"],
"timezone": "America/Toronto"
}'

On create:

  • default_locale defaults to the instance default locale (locale.default in plenary.yaml, en-us unless changed).
  • locales defaults to just the default locale. A list that leaves out the default is refused (422 site_default_locale_not_allowed).
  • timezone defaults to the instance timezone (locale.timezone), or UTC.
  • A taken key returns 409 site_key_taken.

On update, an omitted default_locale, locales, timezone, or config keeps its stored value. An omitted description is cleared, and an omitted is_active sets the site active, so send both when you want to keep them.

A site’s timezone is an IANA name such as America/Denver. The console uses it when editors set Schedule publish and Schedule unpublish on an entry: the times they type are in the site’s timezone, and the editor shows “Timezone: America/Denver” under the inputs. The API always stores and returns UTC, so changing the timezone later does not move schedules already saved. The console’s stats for the site use the same timezone.

Every content model, form, and object model belongs to exactly one site, named by its site_key. A model created in the console belongs to the site selected in the site switcher; through the API, send site_key when you create it. A model cannot move to another site afterwards (422 model_site_key_immutable).

  • The Content catalog shows the models that belong to the selected site.
  • Model keys are unique within a site only, so two sites can each have a page model with its own fields and entries. A request that names a model by key passes ?site_key= (a site-bound API key implies it); when two sites use the key and no site is given, the response is 422 model_site_key_required.
  • A model’s reference and object fields may only point at models on the same site (422 model_reference_cross_site).

To give two sites the same structure, create the model on each site, for example by pushing the same YAML file to both.

Pass the site key on every content read:

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

With the SDK, set siteKey once on the client and override it per call if one app reads several sites:

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: "app",
locale: "en-us",
});
export async function getMarketingHome() {
return plenary.getSingleton("home", { siteKey: "marketing" });
}

A read with no site_key is not limited to one site: a list returns entries from every site the caller can read, and a slug lookup can match an entry on any of them. Always send site_key when your instance has more than one site.

Every public API key belongs to exactly one site, its site_key (422 api_key_sites_required without one):

  • Reads return only entries from the key’s site.
  • A site_key naming another site returns 403 permission_denied.
  • Reads without ?site_key= use the key’s site and its default locale.

A leaked public key therefore exposes only one site’s published content.

A private API key usually belongs to one site too: its grants are held to that site, and a grant naming another site is refused (422 api_key_grant_site_mismatch). A super user can create an instance-wide private key instead, whose grants may each name a site. Roles work like a site-bound key: each role belongs to one site. See API Keys and Permissions.

Besides webhooks on each model, a site can have its own webhooks that fire for changes to any model or form on that site. Use them for site-wide jobs such as rebuilding a static site or clearing a CDN cache. Configure them on the site in Site Management, or with GET and PUT /api/v1/sites/{site_key}/webhooks. See Webhooks for events, payloads, and signing.

Turning a site Inactive keeps its content and media. Inactive sites drop out of the console’s site switcher.

Deleting a site removes it and its webhooks.

  • The last remaining site cannot be deleted (400 site_last_site).
  • A site that still has content entries or form entries is refused (400 site_has_entries) unless you pass purge_content=true, which permanently deletes them. Purged entries record no revisions and cannot be restored. In the console, tick Also permanently delete this site’s entries.
  • A site that still owns content models or forms is refused (400 site_has_models). Delete its models first.
  • confirm_key must equal the site key (400 site_key_confirm_mismatch). Public keys assigned only to a deleted site stop returning content.