EmDash keeps the published version of an entry separate from unpublished changes. The admin panel, REST API, command-line interface (CLI), and Model Context Protocol (MCP) tools use the same lifecycle rules.
An entry can be draft, scheduled, or published. A published entry can also have a draft and a
future schedule: visitors continue to receive the live revision until the scheduled draft is
published. Trash is separate from status. A trashed entry keeps its lifecycle metadata but is
excluded from ordinary content reads.
State transitions
The following table is the canonical contract for content state, revision pointers, and publication timestamps. “No change” means the operation preserves the stored value.
| Action | Starting state | Result | Revision effect | publishedAt | scheduledAt | Repeated call |
|---|---|---|---|---|---|---|
| Save changes | Any active entry | Status does not change | On a revision-enabled collection, replaces the draft revision while the live revision remains public | No change | No change | A supplied _rev refuses a stale save; omitting it makes the REST write unconditional |
| Publish | Draft, scheduled, or published | Published | Promotes the draft revision to live and clears the draft pointer | Set on first publish; preserved on later publishes unless an authorized caller overrides it | Cleared | Preserves the live content and publication time, but returns a new _rev |
| Publish when due | Scheduled, or published with a scheduled draft | Published | Same as publish | Uses the scheduled time on first publish; preserves the existing value when publishing a new draft over live content | Cleared | A later scheduler pass skips an entry whose schedule was already cleared |
| Unpublish | Any active entry | Draft | Clears the live pointer; preserves the existing draft or creates one from the live revision | Preserved | Cleared | An entry that is already a plain draft does not change |
| Schedule | Draft, scheduled, or published | A draft becomes scheduled; a published entry stays published | No change | No change | Set to the requested future time | Replaces the existing schedule and returns a new _rev |
| Unschedule | Scheduled, or published with a schedule | A scheduled entry becomes draft; a published entry stays published | No change | No change | Cleared | An entry without a schedule does not change |
| Discard draft | Any active entry | Status does not change | Clears the draft pointer; the live revision remains unchanged | No change | No change | An entry without a draft does not change |
| Move to Trash | Any active entry | Trashed and absent from ordinary reads | Preserved | Preserved | Preserved | A request for an entry already in Trash returns not found |
| Restore from Trash | Trashed | Draft | Clears the live pointer; preserves any draft pointer | Preserved | Cleared | Requires an entry that is still in Trash |
| Delete permanently | Trashed | Removed | Removes the entry and its revisions | Removed | Removed | Cannot be repeated or undone |
| Restore a revision | Any active entry | Status does not change | On a revision-enabled collection, replaces the draft with a copy of the selected revision; the live revision remains unchanged | No change | No change | Creates a new revision and returns a new _rev |
On a collection without revision support, saves and publishes use the content row instead of live and draft pointers. Restoring a revision writes the selected field values directly to that row.
Restoring a revision on a revision-enabled collection does not publish it. Publish the entry after reviewing the restored draft.
Permissions and write protection
Permissions depend on ownership. An Author can act on an entry they own; an Editor can perform the same action on any entry. Permanent deletion requires an Admin.
Setting publishedAt during publish requires content:publish_any, even when the caller owns the
entry.
The REST API accepts _rev as an optional optimistic-concurrency precondition where shown. MCP tools
require it for the same operations so an agent must read the entry before changing it. A stale token
returns CONFLICT. Admin, REST, and MCP writes protected by an entry lock return ENTRY_LOCKED
unless an authorized request uses the supported lock override.
| Action | Permission | REST _rev | MCP _rev | Entry lock | Hooks |
|---|---|---|---|---|---|
| Save changes | content:edit_own or content:edit_any | Optional | Required | Enforced | content:beforeSave, content:afterSave |
| Publish | content:publish_own or content:publish_any | Optional | Required | Enforced | content:beforePublish, content:afterPublish |
| Unpublish | content:publish_own or content:publish_any | Optional | Required | Enforced | content:beforeUnpublish, content:afterUnpublish |
| Schedule | content:publish_own or content:publish_any | Optional | Required | Enforced | content:beforeSchedule, content:afterSchedule |
| Unschedule | content:publish_own or content:publish_any | Not accepted | Not accepted | Enforced | content:afterUnschedule |
| Discard draft | content:edit_own or content:edit_any | Optional | Required | Enforced | None |
| Move to Trash | content:delete_own or content:delete_any | Not accepted | Not accepted | Enforced | content:beforeDelete, content:afterDelete |
| Restore from Trash | content:edit_own or content:edit_any | Not accepted | Not accepted | Not enforced | content:afterRestore |
| Delete permanently | content:delete_permanent | Not accepted | Not accepted | Not enforced | content:afterDelete |
| Restore a revision | content:edit_own or content:edit_any | Not accepted | Not accepted | Enforced | None |
The content:afterDelete event sets permanent to false when an entry moves to Trash and true
after permanent deletion. Successful after-hooks run after the state change and may run after the
response has been sent. A plugin can reject save, publish, unpublish, schedule, or move-to-Trash from
the corresponding before-hook.
When scheduled publication reaches its due time, it uses the publish hooks. If a
content:beforePublish hook rejects that scheduled attempt, EmDash clears the schedule and runs
content:afterUnschedule.
Conflicts and retries
Use the _rev returned by each read or write for the next protected operation. EmDash refuses an
outdated token instead of replacing a concurrent change. Read the entry again, review the newer
state, and then decide whether to retry.
An error response does not always prove that no state changed. If a connection ends before the client receives a response, read the entry before retrying a lifecycle operation. This also prevents a retry from replacing work completed by another editor.
Revision restore commits the restored content and its audit revision together. If either write fails, EmDash preserves the content and revision history from before the request.
See the REST API reference for HTTP request and response schemas, the MCP server reference for tool inputs, and the hook reference for event payloads.