Skip to content

Content Models

A content model defines one kind of content: the fields an Article, Event, or Page is made of, which site it belongs to, and how its entries are published. Every entry belongs to exactly one model. You create models in the console under Content, through the API, or as YAML files in your repository, and then fetch their entries with the Content API or the SDK.

A model’s kind is chosen when it is created and cannot be changed afterwards.

Kind Entries Read with Use for
collection Any number, each addressed by slug or id GET /api/v1/content/{model_key} returns an array Articles, events, products, pages
singleton One per site and locale GET /api/v1/content/{model_key} returns one entry Site settings, navigation, a homepage
object None of its own Embedded in other models’ object fields A reusable address, SEO block, or button
form Form entries submitted by visitors /api/v1/forms/{form_key} Contact and sign-up forms. See Forms.

Collections and singletons hold the same field types. A second entry on a singleton for the same site and locale is refused with 409 entry_singleton_exists.

Object models have keys starting with obj_ and are usually marked shared so any model can embed them. An object’s values are stored inside the entry that embeds it and are never fetched on their own. See Fields for inline and shared objects.

Forms are created under Forms in the console, not under Content, and use their own API surface.

There is no separate “page” kind. A page is a collection or singleton with a blocks field, which you edit in the Page Builder.

  1. Open Content and select New model. To start from a template (Article, Page, Event, or Person), pick one from the catalog instead; you can edit every field afterwards.
  2. Fill in Name (singular) and Name (plural), such as Article and Articles. The Key is filled in from the name; change it now if you want a different API name, because it is permanent once saved.
  3. Choose the Kind.
  4. Select Add field, pick a type, and name it. Repeat for each field. Turn on Title field on the field that names an entry, usually title or name.
  5. Select Save model.

The model belongs to the site selected in the console’s site switcher. It now appears in that site’s Content catalog, and editors can create entries for it there. To use the model on another site, switch sites and create it there too.

POST /api/v1/models creates a collection, singleton, or object model. It needs a signed-in user or a private API key with content:models:create.

Terminal window
curl -X POST "https://your-instance.plenarycms.io/api/v1/models" \
-H "X-API-KEY: $PLENARY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"key": "article",
"kind": "collection",
"name_singular": "Article",
"name_plural": "Articles",
"title_field": "title",
"active": true,
"site_key": "default",
"fields": [
{ "key": "title", "name": "Title", "type": "text", "required": true },
{ "key": "body", "name": "Body", "type": "rich_text", "settings": { "format": "md" } }
]
}'

The response is 201 with the full model document:

{
"id": "86a0e2be-a692-4b75-9505-d7f3572357a5",
"key": "article",
"name_singular": "Article",
"name_plural": "Articles",
"kind": "collection",
"title_field": "title",
"active": true,
"private": false,
"site_key": "default",
"fields": [
{
"id": "77e05892-a334-4d1a-abad-e762621cefcb",
"key": "title",
"name": "Title",
"type": "text",
"required": true,
"localized": false,
"unique": false,
"private": false,
"sort_order": 1,
"validation": {},
"settings": {},
"ui": {}
}
],
"webhooks": [],
"transformers": [],
"show_preview": false,
"require_change_notes": false,
"track_revisions": true,
"always_published": false,
"open_in_page_builder": false
}

Read a model with GET /api/v1/models/{id_or_key} and list them with GET /api/v1/models. Update one with PUT /api/v1/models/{id}, which replaces the whole definition: send every field you want to keep, with its id.

To manage models as files instead, see Models as Code.

  • key is the model’s API name, used in content URLs such as /api/v1/content/article. It must match ^[a-z][a-z0-9_]*$, must be unique within its site (409 model_key_taken), and cannot be changed after the model is created.
  • name_singular and name_plural are display names. Each must be unique among the site’s models (409 model_name_singular_taken, 409 model_name_plural_taken).
  • description is shown in the console only.

Field keys follow the same pattern and are also permanent. To rename a field, add a new one and move the values over.

title_field names the field whose value becomes each entry’s title. Entry lists in the console show it, and every API response includes it:

{ "id": "c54ffe34-…", "slug": "pastor-mike-degner", "title": "Pastor Mike Degner", "data": { "first_name": "Mike" } }

The title field must be one of text, rich_text, number, date, time, datetime, email, url, phone, select, or computed. To build a title from several fields, add a computed field such as {{data.first_name}} {{data.last_name}} and make that the title field.

title is calculated when an entry is read. You can name it in include and exclude, but you cannot filter or sort on it. Filter on the underlying field instead.

Every collection entry can have a slug, the string you put in its URL. Fetch an entry by slug with GET /api/v1/content/{model_key}/{slug}.

  • Slugs are unique per site, model, and locale (409 entry_slug_taken). Translations of one page share a slug; see Localization.
  • The server stores slugs exactly as sent. It does not generate or reformat them. The console suggests a slug from the title while an entry is new.
  • Writing an entry replaces its slug. An update that leaves slug out clears it.

A slug is the last segment of a URL. To place entries under URL paths such as /blog/campaigns/..., use content directories.

The model editor’s settings map to these model properties:

Console setting Property Default Effect
Active / Inactive active false when omitted from an API create Inactive models are hidden from the Content catalog unless Show inactive is on. Send "active": true when creating a model through the API.
Public / Private private false A private model is invisible to public API keys: reads return 404 model_not_found, as if it did not exist. Signed-in users and private API keys read it per their permissions.
Site (from the site switcher) site_key The one site that owns the model. Required on create (422 model_site_key_required; an unknown site is 422 model_site_not_found), and cannot be changed afterwards (422 model_site_key_immutable).
Show preview show_preview false Gives entries a live preview of your site in the editor. Turning it off clears the preview URL and Open entries in Page Builder.
Preview URL preview_url none The URL template for the preview. See Preview URL.
Open entries in Page Builder open_in_page_builder false Entries open in the Page Builder instead of the form editor.
Track revision history track_revisions true Record a revision for every change to an entry. See Revision history.
Require change notes require_change_notes false Every create, update, delete, and restore of an entry must include a note.
Always published always_published false Entries go live as soon as they are saved. See Always published.

preview_url is a template for the address of an entry on your site, for example:

https://www.example.com/blog/{{slug}}

The template uses the same references as a computed field: bare names for entry properties ({{slug}}, {{locale}}, {{path}}, {{id}}, {{site_key}}, and the other intrinsics) and a data. prefix for fields ({{data.category}}). A reference to an unknown field is refused when the model is saved (422 model_preview_url_unknown_ref). {{title}} is not available.

The console fills in the template from the entry’s last saved values. If any reference is empty, it shows a notice instead of a preview. The URL’s origin is also the only origin the editor exchanges preview messages with. For setting up the receiving side, see Live Preview.

Some content has no use for drafts: site settings, a glossary, a redirects table. With Always published on:

  • Every create writes a published entry, and the editor shows a single Save button with no publish controls or scheduling.
  • Every save is live at once. There are no pending changes on such a model.
  • POST /api/v1/content/{entry_id}/publish succeeds and does nothing. …/unpublish is refused with 409 entry_always_published.
  • A publish_at or unpublish_at on a write is refused with 422 entry_always_published.

Turning the setting on publishes every existing draft of the model, clears pending schedules, and fires entry.published for each entry it publishes. Turning it off changes nothing; drafts become possible again for new changes.

With Track revision history on (the default), every create, update, publish, unpublish, move, delete, and restore of an entry records a revision. Revisions power the entry editor’s History, restoring earlier versions, and archiving: a deleted entry is kept in its history so it can be restored. See Entries & Publishing.

Turning history off deletes the history already recorded for the model’s entries when you save. This cannot be undone. Entries archived earlier lose the history they would be restored from, so they are gone for good. While it is off, entries record no revisions and cannot be restored, every delete is permanent, and Require change notes is switched off. Webhooks still fire. Turning it back on starts a new history from the next change.

The model’s own changes are always recorded, so the history shows who turned the setting off.

Require change notes needs history on. When enabled, a write without a note is refused with 422 entry_note_required, whether it comes from the console, an API key, or a script. Publishing, unpublishing, moving between folders, and scheduled transitions do not need a note. Notes are at most 500 characters.

A reference field links an entry to an entry of another model, such as an article’s author pointing at a person. The field lives on the referencing model.

The other side of the link is called a relationship. On the referenced entry, the editor’s References tab lists every entry pointing at it, grouped by relationship. From there editors can open those entries, link more, or unlink them. Linking and unlinking writes the field on the referencing entry.

By default a relationship is named after the referencing model, such as “Articles”. To give it a better name, rename it from the References tab, or set it with PUT /api/v1/models/{id}/relationships:

Terminal window
curl -X PUT "https://your-instance.plenarycms.io/api/v1/models/$PERSON_MODEL_ID/relationships" \
-H "X-API-KEY: $PLENARY_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"relationships": [
{
"source_model_id": "86a0e2be-a692-4b75-9505-d7f3572357a5",
"source_field_path": "author",
"key": "articles_written",
"label": "Articles written",
"description": "",
"hidden": false
}
]
}'

The array replaces the stored list. hidden: true hides the group from editors who cannot edit the model.

To fetch the entries pointing at an entry, use GET /api/v1/content/{entry_id}/referenced-by with a signed-in user or private key. From a site with a public key, filter the referencing model instead:

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

What happens to references when the target entry is deleted is set by the field’s on_delete setting: restrict refuses the delete, and set_null clears the pointers. See Field Types.

You can change a model’s names, settings, and fields at any time. A few changes have effects on existing content:

  • Key, kind, and field type cannot be changed.
  • Removing a field deletes that field’s values from every entry when you save.
  • Saving the model re-renders computed fields on every entry. Each rewritten entry records a revision attributed to you. On models with many entries the console warns before saving.
  • Changing a shared object updates every model and entry that embeds it.
  • Turning on Always published publishes existing drafts. Turning off Track revision history deletes recorded history.

Every model change is itself recorded in the model’s history. Model history is read-only: you cannot restore a model to an earlier revision.

Open the model, go to Status & deletion, and select Delete model. Type the model key to confirm. If the model has entries, also tick Also delete all content entries; a model that still has entries cannot be deleted.

With the API:

Terminal window
curl -X DELETE "https://your-instance.plenarycms.io/api/v1/models/$MODEL_ID?key_confirm=article&purge_content=true" \
-H "X-API-KEY: $PLENARY_API_KEY"
Parameter Meaning
key_confirm Required. Must equal the model’s key (422 model_key_confirm_mismatch).
purge_content true deletes the model’s entries first. Without it, a model with entries returns 409 model_has_entries.

Deleting a model also deletes its webhooks and drops their pending deliveries. Each purged entry records a delete revision, so the deletion appears in history, but entries of a deleted model cannot be restored: there is no model left to validate them against. Inline object definitions owned by the model are deleted with it; shared objects are kept.