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.
The site object
Section titled “The site object”{ "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. |
Manage sites in the console
Section titled “Manage sites in the console”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.
Manage sites with the API
Section titled “Manage sites with the API”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. |
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_localedefaults to the instance default locale (locale.defaultinplenary.yaml,en-usunless changed).localesdefaults to just the default locale. A list that leaves out the default is refused (422 site_default_locale_not_allowed).timezonedefaults to the instance timezone (locale.timezone), orUTC.- 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.
Timezone
Section titled “Timezone”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.
Models on a site
Section titled “Models on a site”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
pagemodel 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 is422 model_site_key_required. - A model’s
referenceandobjectfields 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.
Read content from a site
Section titled “Read content from a site”Pass the site key on every content read:
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:
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.
API keys and sites
Section titled “API keys and sites”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_keynaming another site returns403 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.
Site webhooks
Section titled “Site webhooks”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.
Deactivate a site
Section titled “Deactivate a site”Turning a site Inactive keeps its content and media. Inactive sites drop out of the console’s site switcher.
Delete a site
Section titled “Delete a site”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 passpurge_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_keymust equal the site key (400 site_key_confirm_mismatch). Public keys assigned only to a deleted site stop returning content.
Related
Section titled “Related”- Localization: locales and translations.
- Content Models: creating a model on a site.
- API Keys: public keys per site.
- Webhooks: model and site webhooks.