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.
Model kinds
Section titled “Model kinds”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.
Create a model in the console
Section titled “Create a model in the console”- 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.
- Fill in Name (singular) and Name (plural), such as
ArticleandArticles. The Key is filled in from the name; change it now if you want a different API name, because it is permanent once saved. - Choose the Kind.
- 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
titleorname. - 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.
Create a model with the API
Section titled “Create a model with the API”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.
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.
Keys and names
Section titled “Keys and names”keyis 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_singularandname_pluralare display names. Each must be unique among the site’s models (409 model_name_singular_taken,409 model_name_plural_taken).descriptionis 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
Section titled “Title field”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
slugout clears it.
A slug is the last segment of a URL. To place entries under URL paths such as /blog/campaigns/..., use content directories.
Model settings
Section titled “Model settings”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
Section titled “Preview URL”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.
Always published
Section titled “Always published”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}/publishsucceeds and does nothing.…/unpublishis refused with409 entry_always_published.- A
publish_atorunpublish_aton a write is refused with422 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.
Revision history
Section titled “Revision history”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.
References and relationships
Section titled “References and relationships”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:
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:
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.
Change a model
Section titled “Change a model”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.
Delete a model
Section titled “Delete a model”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:
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.
Related
Section titled “Related”- Fields: add and configure fields.
- Field Types: every type in detail.
- Entries & Publishing: create, publish, and restore entries.
- Model YAML: the file format for models as code.
- Sites: how models belong to a site.