Skip to content

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.

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.
  1. Open Content, find the model, and select Open entries. For a singleton, select Edit entry.
  2. Select Add {model name}, such as Add Article.
  3. Fill in the fields. Under the metadata, set the URL Slug, Locale, and Folder.
  4. Select Save Changes to save a draft, or Save and Publish to make it live in one step.

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.)

Terminal window
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.

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):

scripts/update-title.ts
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:update
const 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 without hydrate: when you plan to write.
  • A user field’s resolved user / users profile must be removed.
  • Computed values and image variants maps 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.

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.

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.

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:

Terminal window
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_at on 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 PUT replaces the entry, an update that leaves out publish_at cancels 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_interval in plenary.yaml.
  • Scheduled transitions pause while the instance has no valid license, and resume when it does.

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:

Terminal window
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.

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:

Terminal window
# 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.

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:

Terminal window
# Archive
curl -X DELETE "https://your-instance.plenarycms.io/api/v1/content/$ENTRY_ID" \
-H "X-API-KEY: $PLENARY_API_KEY"
# Delete permanently
curl -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.

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.

List a model’s archived entries, then restore the delete revision each one names:

Terminal window
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" }
}
]
Terminal window
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).

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.

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.

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.

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.