DocsData
Drafts and publishing
A working copy for any collection’s entries, published now or at a set time, with every version kept.
Any collection can work like a CMS. Changes are saved as a draft that only editors see, and go live when you publish them, now or at a time you set. The collection’s own records are what is published, so everything that reads them (the REST API, sync, rules, your app) keeps seeing only published content, with nothing to change.
This comes with the content plugin (sluurp plugin add content). To make a collection content, name it in /api/content, or in a migration:
{ "content": { "collections": ["articles"], "locales": ["en", "fr"] } }Features include:
- Drafts, scheduled publishing, and every published version kept
- Addresses, languages, translations and search metadata on each entry
- Previews of a draft on the real page, and links to share them
- Bodies in blocks, a media library, and imports from Markdown, WordPress and Strapi
- Roles for writers, editors and publishers, and a ready-made editor
In the admin
Open a content collection in the admin, and its entries are edited as drafts. The sheet shows where an entry stands, its fields, and a Publishing section with:
- its address (made from the title if left empty);
- its language;
- its title and description for search and sharing;
- a time to publish it at.
Save draft keeps the working copy. Publish puts it live now, or schedules it when a time is set. Discard the draft, in the sheet’s menu, drops the changes. The collection lists its drafts, including entries never published, above its records.
Save a draft
PUT /api/collections/articles/records/new/draft
{ "data": { "title": "Hello", "body": "First version" } }new makes a new entry, and the answer gives its id. To change a published entry, save a draft with its id: only the fields you send change when it’s published. Save as often as you like; nobody else sees it.
Read a draft
GET /api/collections/articles/records/{id}/draftThis answers the working copy (the published fields with the draft’s on top), the published record, and where the entry stands:
| State | Means |
|---|---|
draft | Never published yet |
published | Live, with no changes waiting |
changed | Live, with a draft of changes waiting |
scheduled | A draft set to be published at a time |
To list a collection’s drafts, the latest changed first, call GET /api/collections/articles/drafts.
Publish
POST /api/collections/articles/records/{id}/publish
POST /api/collections/articles/records/{id}/publish { "at": "2026-11-01T09:00:00+01:00" }Without a time, the draft goes live at once. With a time in the future, it is scheduled, and published within a minute of that time. Publishing is an ordinary create or update, so the collection’s rules, hooks and realtime updates apply as they do to any save.
To drop a draft, call DELETE /api/collections/articles/records/{id}/draft. The published version doesn’t change.
Content fields
When a collection becomes content, Sluurp adds and keeps a few fields for it. Like everything Sluurp manages, their names start with _:
| Field | What it holds |
|---|---|
_slug | Its address, made from its title (Héllo Wörld → hello-world) and kept unique in its language (hello-world-2) |
_seo | A title, a description and an image for search and sharing |
_locale | Its language: the site’s first, if not given |
_of | The entry it translates, for the same content in several languages |
_published | When it was first published |
Over HTTP:
PUT /api/content { "collections": ["articles"], "locales": ["en", "fr"] }Your own fields stay as they are. To find a published entry by its address, as the collection’s rules let the caller see it:
GET /api/collections/articles/slug/hello-world?locale=frShow it on a site
The content plugin gives a page what is published. Add it once; it brings the blocks plugin, which draws a body:
sluurp plugin add contentIt then gives a React page what is published, as hooks:
import { useEntries, useEntry } from "@sluurp-plugins/content/client/index.ts";
const posts = useEntries("articles", { locale: "fr", perPage: 10 });
const post = useEntry("articles", "hello-world");Both read the delivery API, which answers only with published entries, as the collection’s rules let the reader see them. The browser keeps each answer and asks again cheaply.
GET /api/content/articles?locale=fr&page=1&perPage=10
GET /api/content/articles/hello-world?locale=frFor search engines
useEntries and useEntry fill a page in the browser. A server page sends it finished instead, which is what search engines and link previews read. To render an entry on the server, await it in a page at its address:
import { getEntry } from "@sluurp-plugins/content/client/index.ts";
import { Body } from "../../components/body.tsx"; // "use client"; export { Body } from the plugin's client/body.tsx
export default async function Post({ params }) {
const post = await getEntry("articles", params.slug);
return <article><h1>{post?.title}</h1><Body blocks={post?.body} /></article>;
}Once the collection’s address is set (see Previews; /blog/{slug} here), Sluurp adds the rest:
- the page’s head gets the entry’s title, description, share picture, canonical address, and its other languages (
hreflang); /sitemap.xmllists every published entry, in every language;/blog/feed.xmlis an Atom feed of the latest entries.
An address can hold the language too: /{locale}/blog/{slug}.
Translations
With more than one language, an entry’s sheet shows its Languages: each translation, published or drafted, and Translate to … for each language it isn’t in yet. That starts a draft in the new language, linked to the original (_of) and copied from it to write over, with the original kept in view. Publishing the draft makes it one of the entry’s languages, with hreflang links between them on the site.
GET /api/collections/articles/records/{id}/translations
POST /api/collections/articles/records/{id}/translate { "locale": "fr" }Agents translate too: save_draft with entry: "new", _locale and _of, and the fields written in the new language.
Import entries
Import, on a content collection in the admin, brings entries in from elsewhere:
| From | What’s kept |
|---|---|
| Markdown files | Frontmatter title, slug (else the file name), date, description, tags, lang; a first # Heading as the title |
A WordPress export (WXR .xml) | Posts’ titles, addresses, publication dates, excerpts, tags and categories |
Strapi entries (.json) | title, slug, publishedAt, locale, description, and any field the collection has by the same name; Markdown or Strapi blocks as the body |
Bodies become blocks in a json body field, or text in a text one. Entries are published with their own dates, or brought in as drafts. Pictures stay at the addresses they had.
POST /api/content/articles/import { "format": "markdown", "files": [{ "name": "hello.md", "text": "…" }] }
POST /api/content/articles/import { "format": "wordpress", "text": "<rss …>", "drafts": true }Sluurp reads an export’s XML with document type definitions refused: no entities are expanded, and nothing outside the file is ever read.
Example: a blog
The blog example is a blog built only on this: posts in English and French with their translations linked, tags, an Atom feed per language and a sitemap. One migration holds the collection, the content model and sample posts:
{
"collections": [{ "name": "articles", "schema": [{ "name": "title", "type": "text" }, { "name": "body", "type": "json" }], "rules": { "list": "", "view": "" } }],
"content": { "collections": ["articles"], "locales": ["en", "fr"], "previews": { "articles": "/{locale}/{slug}" } }
}Its pages are routes/[locale]/index.tsx (the list) and routes/[locale]/[slug].tsx (a post).
Previews
To say where a collection’s entries are shown on the site:
PUT /api/content { "previews": { "articles": "/blog/{slug}" } }The editor then has a Preview section. Show preview opens the entry’s page beside the fields, with the draft in it, and the page changes as you type. Copy preview link gives a link anyone can open to see the draft for a week, without signing in.
A page opened from a preview link has ?preview= in its address, and useEntry reads the draft instead of what is published. Nothing else on the page needs to change.
Bodies in blocks
Give a content collection a json field called body (or content, or blocks), and the admin edits it in blocks, as a page is: headings, lists, quotes, code, pictures and more, with / to choose. A site renders it with Body, plainly on the server and as the Blocks plugin draws it in the browser:
import { Body, useEntry } from "@sluurp-plugins/content/client/index.ts";
const post = useEntry("articles", "hello-world");
<article><Body blocks={post?.body} /></article>Media
Media, in the admin, holds the project’s pictures and files. Drop them on the page or choose them with Upload. Open one to describe it for people who can’t see it, add a caption or a folder, copy its address, or delete it. An entry’s Picture when shared is chosen from here.
Anyone can read them, as with any site’s pictures. Each has its own address, and is resized on the way out:
<img src="/api/files/_media/{id}/file?w=800" alt="…">The library is the _media collection, so the records API lists and searches it like any other: GET /api/collections/_media/records.
React to publishing
Publishing an entry emits content.published, and sending one for review emits content.review, as events. An agent can act on them, to rebuild a static site, clear a cache, or call any webhook:
export const watch = { event: "content.published" };
export async function act({ event }) {
await fetch("https://api.example.com/deploy-hook", { method: "POST", body: JSON.stringify(event.data) });
}event.data has the collection, the entry’s id, slug, locale, its address on the site, and who published it (by). The admin’s sidebar counts the drafts waiting for review beside their collection.
Coding agents
Coding agents connected to Sluurp read and write content too:
| Tool | Does |
|---|---|
content_model | The content collections and their fields, the languages, and where entries are shown |
list_entries, read_entry | Published entries, and one by id or address with its draft |
list_drafts, list_media | The drafts waiting, and the media library’s pictures |
save_draft | A draft of a new entry or of changes, sent for review with review: true |
An agent writes as a writer named agent, and each draft it saves can be undone in AI › Agents. It never changes a draft a person wrote, and never publishes: a person reviews its drafts and publishes them. A read-only key reads and writes nothing.
Versions
A collection keeps its history from its first draft. Each published version is in the entry’s history (GET /api/collections/articles/records/{id}/history), to compare and go back to.
Roles
Give people one of three roles, and drafts and publishing are theirs as well as superusers’:
| Role | May |
|---|---|
writer | Write new entries and change their own drafts, send them for review, add pictures to Media |
editor | All a writer may, on anyone’s drafts, and discard them |
publisher | All an editor may, and publish or schedule |
A draft keeps its writer when an editor changes it. A writer sends a draft for review by saving it with "review": true, and it shows as review until it’s published.
To build an app’s own editor, use drafts:
import { drafts } from "@sluurp-plugins/content/client/index.ts";
const articles = drafts(sluurp, "articles");
const { id } = await articles.save("new", { title: "Hello" });
await articles.save(id, {}, { review: true });
await articles.publish(id);Each call is allowed or refused by the signed-in person’s role, and articles.role() says which they have.
For a whole editorial screen, ready made:
import { ContentEditor } from "@sluurp-plugins/content/client/editor.tsx";
<ContentEditor client={sluurp} collection="articles" />It lists what is in review, the drafts and what is published, and opens an entry with its fields (a body in blocks), its address, language and description. Writers get Send for review, publishers Publish, and editors and publishers Discard.