Entries & Publishing
An entry is one record of a content model: one article, one event, the one settings document of a singleton. Every entry belongs to one site and one locale, and is either a draft or published. Public API keys only read published entries, so publishing is what puts content on your site. Editing a published entry does not change the site by itself: the edit waits as pending changes until it is published.
The entry object
Section titled “The entry object”Every read returns entries in this shape:
{ "id": "285e3e7f-c343-45b0-8df3-1325b1495448", "site_key": "default", "model_key": "congregation", "slug": "advent-lutheran-church-westminster-co", "locale": "en-us", "title": "Advent Lutheran Church - Westminster, CO", "status": "published", "published_at": "2026-09-10T12:07:55.659Z", "publish_at": null, "unpublish_at": null, "created_at": "2026-08-12T11:14:14.539Z", "updated_at": "2026-09-10T12:07:55.659Z", "data": { "name": "Advent Lutheran Church", "phone_number": "+13034287501" }, "folder_id": "d2a46420-7a21-41f2-b2f1-bc9884937a9c", "path": "/metro-west", "draft": null}| Property | Meaning |
|---|---|
id |
The entry’s UUID. Stable for the life of the entry, including after an undelete. |
site_key |
The site the entry belongs to. |
slug |
URL segment, unique per site, model, and locale. null if unset. |
locale |
Lowercase language tag such as en-us. See Localization. |
title |
The value of the model’s title field, or null. |
status |
draft or published. |
published_at |
When the entry was last published. Kept after an unpublish. |
publish_at, unpublish_at |
Pending scheduled transitions, or null. |
data |
Field values, keyed by field key. See Field Types. |
folder_id, path |
The entry’s folder. See Content Directories. |
draft |
A published entry’s pending changes, { "data": …, "slug": …, "updated_at": … }, or null. Only private keys and signed-in users see it. |
Create an entry in the console
Section titled “Create an entry in the console”- Open Content, find the model, and select Open entries. For a singleton, select Edit entry.
- Select Add {model name}, such as Add Article.
- Fill in the fields. Under the metadata, set the URL Slug, Locale, and Folder.
- Select Save Changes to save a draft, or Save and Publish to make it live in one step.
Create an entry with the API
Section titled “Create an entry with the API”POST /api/v1/content/{model_key}?site_key={site_key} creates an entry. It needs a signed-in user or a private API key with content:entries:create. site_key is required.
Field values go in a fields object. (Reads return them in data; a write that sends data instead is treated as having no fields.)
curl -X POST "https://your-instance.plenarycms.io/api/v1/content/article?site_key=default" \ -H "X-API-KEY: $PLENARY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "slug": "spring-sale", "locale": "en-us", "fields": { "title": "Spring sale starts Monday", "body": "Everything in the shop is 20% off this week." } }'| Body key | Type | Meaning |
|---|---|---|
fields |
object | Field values. Unknown keys are refused (422 entry_field_unknown). |
slug |
string | Optional. Unique per site, model, and locale. |
locale |
string | Optional. Defaults to the site’s default locale. Must be one of the site’s locales. |
folder_id |
string or null |
Optional folder. A new translation of an existing entry joins its folder automatically. |
publish_at, unpublish_at |
RFC 3339 timestamp or null |
Optional schedule. Must be in the future. |
note |
string | Optional change note for the revision (required when the model requires change notes). |
The response is 201 with the entry. New entries are drafts, unless the model is always published.
Update an entry
Section titled “Update an entry”PUT /api/v1/content/{entry_id} replaces the entry. Everything in the body is the new state, and anything you leave out is cleared or reset:
| Left out | Result |
|---|---|
a key in fields |
That field is cleared. |
slug |
The slug is cleared. |
locale |
The locale resets to the site’s default locale. |
folder_id |
The entry, and all its translations, move to the root folder. |
publish_at / unpublish_at |
The schedule is cleared. |
To change one field, read the entry first and send everything back. Run this with npx tsx scripts/update-title.ts <entry id> (Node 18 or later):
export {}; // makes this file a module, so top-level await works
const baseUrl = process.env.PLENARY_BASE_URL!;const apiKey = process.env.PLENARY_API_KEY!; // a private key with content:entries:updateconst entryId = process.argv[2];
const headers = { "X-API-KEY": apiKey, "Content-Type": "application/json" };
const res = await fetch(`${baseUrl}/api/v1/content/article/${entryId}`, { headers });if (!res.ok) throw new Error(`read failed: ${res.status}`);const entry = await res.json();
const update = await fetch(`${baseUrl}/api/v1/content/${entryId}`, { method: "PUT", headers, body: JSON.stringify({ slug: entry.slug, locale: entry.locale, folder_id: entry.folder_id, publish_at: entry.publish_at, unpublish_at: entry.unpublish_at, fields: { ...entry.data, title: "Spring sale extended" }, }),});if (!update.ok) throw new Error(`update failed: ${update.status} ${await update.text()}`);console.log(await update.json());A value read from the API can be written back as is, with three exceptions:
- A hydrated reference (read with
hydrate:) must be reduced to{ "reference_id": "…" }. Read withouthydrate:when you plan to write. - A
userfield’s resolveduser/usersprofile must be removed. - Computed values and image
variantsmaps are fine to send back; the server ignores them.
Updating an entry needs content:entries:update. Saving a published entry does not change the live content: the new field values and slug are stored as the entry’s pending changes, and the site keeps serving what it served before until the entry is published again. When you read a published entry to update it, start from draft.data and draft.slug when draft is set, so one update does not throw away the last.
Draft and published
Section titled “Draft and published”An entry’s status is draft or published. There is no archived state.
| Action | Console | API | Effect |
|---|---|---|---|
| Publish | Publish, or Save and Publish | POST /api/v1/content/{entry_id}/publish |
status becomes published and published_at is set to now. Clears a pending publish_at. On an entry that is already published, makes its pending changes live. |
| Unpublish | Unpublish | POST /api/v1/content/{entry_id}/unpublish |
status becomes draft. published_at is kept. Clears a pending unpublish_at. With pending changes, takes ?draft=merge or ?draft=discard. |
Both need content:entries:publish, return the updated entry, record a revision, and fire the entry.published or entry.unpublished webhook. Neither takes a request body.
Models with Always published on skip this step entirely. See Content Models.
Pending changes on a published entry
Section titled “Pending changes on a published entry”A published entry can be edited without the edit reaching the site. Saving a published entry stores the new field values and slug as the entry’s pending changes, in its draft property, and leaves data and slug as they are live. The entry stays published. Publishing it again makes the pending changes live; discarding them throws them away.
In the console, a published entry with pending changes shows the status Changes pending. The editor shows the pending copy, which is what Save Changes saves to, and the publishing card offers Publish changes and Discard changes beside Unpublish. Save and Publish saves and publishes in one step. The entry list can filter on Changes pending, and Group actions offers Publish changes for a selection. The dashboard’s content breakdown has a Changes pending column.
Through the API:
| Action | Request | Effect |
|---|---|---|
| Save pending changes | PUT /api/v1/content/{entry_id} on a published entry |
The body goes through the normal save (validation, transformers, computed fields, slug and unique checks) and the result is stored in draft. The live data and slug are untouched, updated_at does not move, and no webhook fires. A body identical to the live copy stores nothing and clears any pending changes. |
| Publish the changes | POST /api/v1/content/{entry_id}/publish |
data and slug take the pending values, published_at is set to now, draft is cleared, and entry.published fires with changed naming the fields that went live. |
| Discard the changes | DELETE /api/v1/content/{entry_id}/draft |
draft is cleared. 404 entry_draft_not_found when nothing is pending. Takes ?note= like a delete. Needs content:entries:update. |
| Unpublish with changes pending | POST /api/v1/content/{entry_id}/unpublish?draft=merge or ?draft=discard |
merge makes the pending changes the draft entry’s content; discard keeps the live content and drops the pending changes. Without draft= the request is refused with 409 entry_draft_pending; any other value is 400 entry_draft_choice_invalid. |
A slug or unique field value is checked against every other entry’s live and pending copy, so two entries cannot be queued to collide on publish. Linking and unlinking references, moving the entry between folders, and model changes that rewrite entries (a removed or renamed field, a changed computed source) apply to the live and the pending copy alike.
Pending changes show in the entry’s history as Draft saved and Changes discarded revisions (draft and discard actions). A revision’s diff shows the pending content when the entry had some at the time.
where:has_draft=true lists the entries with pending changes (false lists the rest). It takes $eq only, and a public key may not use it (400 entry_query_invalid).
Models with Always published on have no pending changes: a save there is live at once.
Schedule publishing
Section titled “Schedule publishing”An entry can carry a future publish_at, unpublish_at, or both. A background job checks every minute and publishes or unpublishes entries whose time has passed. Scheduled transitions record a revision by the scheduler system actor and fire the same webhooks as a manual publish.
In the console, set Schedule publish and Schedule unpublish on the entry and save. The times you type are in the site’s timezone, shown under the inputs as “Timezone: …”. The entry list shows scheduled entries with a Scheduled status.
Through the API, send RFC 3339 timestamps. Any offset is accepted and stored as UTC:
curl -X PUT "https://your-instance.plenarycms.io/api/v1/content/$ENTRY_ID" \ -H "X-API-KEY: $PLENARY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "slug": "spring-sale", "locale": "en-us", "publish_at": "2026-11-02T09:00:00-07:00", "unpublish_at": "2026-11-09T09:00:00-07:00", "fields": { "title": "Spring sale starts Monday" } }'{ "status": "draft", "publish_at": "2026-11-02T16:00:00Z", "unpublish_at": "2026-11-09T16:00:00Z" }Rules:
- Both times must be in the future (
422 entry_publish_at_past,422 entry_unpublish_at_past). - A
publish_aton a published entry with pending changes publishes those changes at that time (the console labels it Publish changes at). A scheduled unpublish of such an entry keeps the pending changes as the draft’s content, like?draft=merge. - Because
PUTreplaces the entry, an update that leaves outpublish_atcancels the schedule. - Scheduling is refused on always-published models (
422 entry_always_published). - Self-hosted operators can change the check interval with
content.schedule_sweep_intervalinplenary.yaml. - Scheduled transitions pause while the instance has no valid license, and resume when it does.
What each reader sees
Section titled “What each reader sees”The same endpoints serve every caller. What comes back depends on the credential:
| Reader | Drafts | Private models | Private fields | Sites |
|---|---|---|---|---|
| Public API key | No. A draft is 404 by slug or id and absent from lists. |
No (404 model_not_found) |
No | Only the key’s site (403 for others) |
| Public API key with include drafts | Yes | No | No | Only the key’s site |
| Private API key | Yes, if its grants allow reading the model | Yes | Yes | Per its grants |
| Signed-in user | Yes, per their role | Yes | Yes | Per their role |
A published entry’s pending changes follow the same split. A public key reads the live data and slug and never sees draft. A public key with include drafts reads the pending data and slug in place of the live ones, since a preview wants the content a publish would make live, and still never sees draft itself. A private key or user session reads the live copy plus draft.
A private key or user session returns drafts and published entries together. When you render a live site with one, filter to published content yourself:
curl "https://your-instance.plenarycms.io/api/v1/content/article?site_key=default&locale=en-us&where:status=published" \ -H "X-API-KEY: $PLENARY_API_KEY"For draft previews, use a public key with include drafts or a private key on the server. See API Keys and Live Preview.
Revisions and restore
Section titled “Revisions and restore”Every change to an entry records a revision: create, update, publish, unpublish, folder move, delete, restore, and a published entry’s pending changes being saved (draft) or discarded (discard). Each revision stores a full snapshot of the entry, who made the change, and an optional note. Models with Track revision history off record none.
In the console, open the entry and select History. Select a revision to see what changed, then Restore this revision… to make the entry match it.
With the API:
# List an entry's revisions, newest first (needs content:revisions:read)curl "https://your-instance.plenarycms.io/api/v1/content/$ENTRY_ID/revisions" \ -H "X-API-KEY: $PLENARY_API_KEY"
# Restore one (needs content:entries:update)curl -X POST "https://your-instance.plenarycms.io/api/v1/revisions/$REVISION_ID/restore" \ -H "X-API-KEY: $PLENARY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "note": "Revert the pricing change" }'Each item in the revision list looks like this:
{ "id": "a12a4e02-e544-44fe-9144-26e8a9c0c281", "target_type": "entry", "target_id": "285e3e7f-c343-45b0-8df3-1325b1495448", "site_key": "default", "locale": "en-us", "action": "publish", "actor": { "type": "user", "id": "6063d721-…", "label": "editor@example.com" }, "created_at": "2026-09-10T12:07:55.66Z", "changed": ["published_at", "status"]}Restoring replays the revision’s field values and slug through a normal save, so validation, transformers, and computed fields all apply, and a slug taken since then fails with 409 entry_slug_taken. The entry’s status, schedule, and folder are left as they are: restoring old copy never unpublishes a live page. On a published entry the restored content lands as pending changes, so it does not change the page either until someone publishes it; the console’s confirmation says so. A revision taken while the entry had pending changes restores that pending content. The restore is recorded as a new revision, so nothing is lost.
Archive and delete
Section titled “Archive and delete”When a model tracks revision history, removing an entry can mean two things:
| Archive | Delete | |
|---|---|---|
| What goes | The entry. Its history stays, ending in a delete revision that keeps the entry’s last content. | The entry and its whole revision history. |
| Can be undone | Yes: restore it from Archived. | No. |
| API | DELETE /api/v1/content/{entry_id} |
DELETE /api/v1/content/{entry_id}?permanent=true |
| Change note | Required when the model has Require change notes on, as ?note= |
Never required, because no revision is recorded |
| Webhook | entry.deleted |
entry.deleted, unless the entry was already archived |
A plain DELETE archives. Add ?permanent=true to delete for good. Both need content:entries:delete, and both answer with the same body:
# Archivecurl -X DELETE "https://your-instance.plenarycms.io/api/v1/content/$ENTRY_ID" \ -H "X-API-KEY: $PLENARY_API_KEY"
# Delete permanentlycurl -X DELETE "https://your-instance.plenarycms.io/api/v1/content/$ENTRY_ID?permanent=true" \ -H "X-API-KEY: $PLENARY_API_KEY"{ "id": "ff86df90-b08a-4836-87cf-109ddb195183", "deleted": true }An entry has no archived status: an archived entry no longer exists as an entry. Reads answer 404, it drops out of lists, and its slug is free for a new entry. What remains is its history, which is how the Archived view finds it and how a restore brings it back.
If another entry references this one through a field with on_delete: restrict, or a required single reference, both requests are refused with 409 entry_referenced, naming what is in the way. Otherwise, references to the entry are cleared when it goes.
When a model has Track revision history off, there is nothing to archive into: every delete is permanent, with or without ?permanent=true, and the console offers only Delete. Turning history off also discards the history of entries archived earlier, so they can no longer be restored. See Revision history.
In the console
Section titled “In the console”The entry editor and the entry list’s group actions offer Archive and Delete side by side. Archive asks for confirmation and moves the entry to the model’s Archived view. Delete warns that the entry’s history goes with it and cannot be undone.
In the entry list, select Archived to open Archived entries for the model. Each row offers Restore and Delete: Delete there permanently removes an entry that is already archived.
Restore an archived entry
Section titled “Restore an archived entry”List a model’s archived entries, then restore the delete revision each one names:
curl "https://your-instance.plenarycms.io/api/v1/content/article/entries/archived?site_key=default" \ -H "X-API-KEY: $PLENARY_API_KEY"[ { "id": "ff86df90-b08a-4836-87cf-109ddb195183", "revision_id": "7cfccf08-b33d-4bd1-bd1d-2930400ef232", "title": "Spring sale", "slug": "spring-sale", "locale": "en-us", "site_key": "default", "archived_at": "2026-10-07T09:18:26.812Z", "actor": { "type": "user", "id": "6063d721-…", "label": "editor@example.com" } }]curl -X POST "https://your-instance.plenarycms.io/api/v1/revisions/7cfccf08-b33d-4bd1-bd1d-2930400ef232/restore" \ -H "X-API-KEY: $PLENARY_API_KEY"A restored entry comes back under its original id, with its history intact, as a draft, holding the pending changes it had when it was archived if it had any. On an always-published model it comes back published. Fields the model no longer has are dropped, and if its folder was deleted it lands at the root. Restoring needs both content:entries:update and content:entries:create; listing archived entries needs content:revisions:read. The list returns 50 entries by default (limit up to 200, and offset), newest first. Entries of a deleted model cannot be restored (restore_model_missing).
Delete an archived entry
Section titled “Delete an archived entry”Send DELETE /api/v1/content/{entry_id}?permanent=true with the archived entry’s id to remove its history. It no longer appears in the archived list and cannot be restored. No webhook fires, because subscribers received entry.deleted when the entry was archived. Without ?permanent=true, an archived entry’s id answers 404 entry_not_found.
If a permanent delete fails after the entry itself is removed, the entry is left archived; send the request again to finish it.
Bulk actions
Section titled “Bulk actions”In an entry list, select entries with the checkboxes. Group actions offers Publish, Publish changes, Unpublish, Archive…, and Delete… for the selection, and Move to… moves them to a folder. A bulk unpublish skips entries with pending changes and says so, since each needs the merge-or-discard choice. Each entry is processed on its own, so one failure (for example an archive blocked by a reference) does not stop the rest; the console reports which entries failed and why.
The API has a bulk endpoint only for folder moves (POST /api/v1/content/{model_key}/entries/move). Publish, archive, and delete one entry per request.
Change notes
Section titled “Change notes”A revision can carry a note describing why a change was made. In the console, use Save with note… or Publish with note…. In the API, send note in the create, update, or restore body, or ?note= on an archive or a discard of pending changes. A permanent delete takes no note. Notes are trimmed and limited to 500 characters (422 entry_note_too_long).
When a model has Require change notes on, creates, updates, archives, and restores without a note are refused with 422 entry_note_required. A permanent delete records no revision, so it never needs one. Publishing, unpublishing, folder moves, and scheduled transitions never need one.
Common errors
Section titled “Common errors”| Status | Code | Cause |
|---|---|---|
422 |
entry_site_key_required |
Create without ?site_key=. |
422 |
entry_model_not_in_site |
A restored revision names a model on another site. Only revisions recorded before each model belonged to one site can. |
422 |
entry_locale_not_allowed |
The locale is not in the site’s locales. |
422 |
entry_field_required |
A required field is missing or empty. |
422 |
entry_field_unknown |
fields has a key the model does not define. |
422 |
entry_field_schema_invalid |
A value has the wrong shape for its type. |
409 |
entry_slug_taken |
Another entry has this slug for the same site, model, and locale. |
409 |
entry_field_value_taken |
A unique field’s value is already used. |
409 |
entry_singleton_exists |
The singleton already has an entry for this site and locale. |
409 |
entry_referenced |
A restricting reference blocks the archive or delete. |
409 |
entry_draft_pending |
Unpublish of an entry with pending changes without ?draft=merge or ?draft=discard. |
400 |
entry_draft_choice_invalid |
?draft= is something other than merge or discard. |
404 |
entry_draft_not_found |
Discard on an entry with nothing pending. |
The full list is in the Errors reference.
Related
Section titled “Related”- Content API: every read and write endpoint.
- Localization: translations of an entry.
- Content Directories: folders and paths.
- Webhooks: react to publishes and edits.