Content Directories
Content directories let editors file a model’s entries into folders, such as /blog/campaigns or /docs/getting-started, instead of one flat list. Each entry exposes its folder as a path you can query and route on, so a site can serve nested URLs straight from the folder tree. Folders are per model and per site, and are most useful for collections with many entries, such as pages or articles.
Folders, paths, and slugs
Section titled “Folders, paths, and slugs”A folder has a display name and a URL slug, and can be nested to any depth. Folders hold no fields; they only organize entries.
Every entry carries two read-only properties for its placement:
| Property | Example | Meaning |
|---|---|---|
folder_id |
"4feda7eb-2140-4f6e-be2c-09056509f675" |
The containing folder, or null at the root. |
path |
"/blog/campaigns" |
The folder’s path: a leading slash and the slugs of each folder down to it. "/" at the root. |
path is the directory only. It does not include the entry’s own slug. An entry with path /blog/campaigns and slug spring-sale naturally lives at /blog/campaigns/spring-sale on your site:
{ "id": "ff86df90-b08a-4836-87cf-109ddb195183", "slug": "spring-sale", "locale": "en-us", "folder_id": "c45d9d64-9663-4b5d-99be-d878b07a2b99", "path": "/blog/campaigns"}Folder slugs must be lowercase letters and digits separated by single hyphens (^[a-z0-9]+(?:-[a-z0-9]+)*$). Entry slugs are not checked by the server, so keep them URL-safe yourself.
Folder placement belongs to the whole entry, not to one translation: every translation of an entry (same model, site, and slug) is always in the same folder. Moving one moves them all, so path is the same in every locale.
Organize entries in the console
Section titled “Organize entries in the console”Open a model’s entries from Content. The Folders panel beside the list shows the tree for the selected site.
- New folder creates a folder at the root; New subfolder creates one inside the selected folder. Give it a Name and URL Slug.
- Rename changes a folder’s name or slug. Delete removes it (see Delete a folder).
- To move entries, select them and choose Move to…, or drag them onto a folder.
- In the entry editor, the Folder setting shows where the entry lives. None (root) puts it at the top level.
A new entry created while you are browsing a folder is placed in that folder.
Route a nested URL
Section titled “Route a nested URL”To serve /blog/campaigns/spring-sale, split the URL into the folder path and the last segment, then query both:
curl "https://your-instance.plenarycms.io/api/v1/content/page?site_key=default&locale=en-us&where:path=/blog/campaigns&where:slug=spring-sale" \ -H "X-API-KEY: $PLENARY_API_KEY"The result is an array with zero or one entry. With the SDK:
import { createClient } from "@plenary/client";
const plenary = createClient({ baseUrl: process.env.PLENARY_BASE_URL!, apiKey: process.env.PLENARY_API_KEY!, siteKey: process.env.PLENARY_SITE_KEY!, locale: "en-us",});
// "/blog/campaigns/spring-sale" -> path "/blog/campaigns", slug "spring-sale"export async function getPageByUrl(url: string) { const segments = url.split("/").filter(Boolean); const slug = segments.pop(); if (!slug) return null; const path = "/" + segments.join("/");
const { items } = await plenary.listEntries("page", { where: { path, slug }, limit: 1, }); return items[0] ?? null;}A page at the root of the model has path "/", which the code above produces for a single-segment URL such as /about.
To generate every URL for a static build, list entries with just the fields you need and join them:
import { createClient } from "@plenary/client";
const plenary = createClient({ baseUrl: process.env.PLENARY_BASE_URL!, apiKey: process.env.PLENARY_API_KEY!, siteKey: process.env.PLENARY_SITE_KEY!, locale: "en-us",});
export async function allPageUrls(): Promise<string[]> { const { items } = await plenary.listEntries("page", { include: ["slug", "path"], limit: 500, }); return items .filter((entry) => entry.slug) .map((entry) => (entry.path === "/" ? `/${entry.slug}` : `${entry.path}/${entry.slug}`));}limit is at most 500 per request; page with offset and count: true for more.
Query a folder or subtree
Section titled “Query a folder or subtree”| Goal | Query |
|---|---|
Entries directly in /blog |
?where:path=/blog |
Entries in /blog and every folder beneath it |
?where:path.$under=/blog |
| Entries at the model root only | ?where:path=/ or ?where:folder_id.$is_null=true |
| Entries in a folder by id | ?where:folder_id=<folder id> |
$under matches the path itself and everything below it: /blog, /blog/campaigns, /blog/campaigns/2026, but not /blogroll. Do not use $like for this: where:path.$like=/blog% also matches /blogroll. $under only works on path, and its value must start with / (400 entry_query_invalid otherwise). ?where:path.$under=/ matches every entry.
path and folder_id also work in sort:, include, and exclude, and public API keys can read and filter them.
Folders API
Section titled “Folders API”All folder routes take ?site_key= (required) and work on one model’s tree for that site.
| Method | Path | Permission | Body |
|---|---|---|---|
GET |
/api/v1/content/{model_key}/folders?site_key= |
content:entries:read |
|
POST |
/api/v1/content/{model_key}/folders?site_key= |
content:entries:update |
name, slug, optional parent_id, sort_order |
PUT |
/api/v1/content/{model_key}/folders/{id}?site_key= |
content:entries:update |
name, slug, parent_id, sort_order |
DELETE |
/api/v1/content/{model_key}/folders/{id}?site_key= |
content:entries:update |
|
POST |
/api/v1/content/{model_key}/entries/move?site_key= |
content:entries:update |
entry_ids (array), folder_id (null for the root) |
curl -X POST "https://your-instance.plenarycms.io/api/v1/content/page/folders?site_key=default" \ -H "X-API-KEY: $PLENARY_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "name": "Campaigns", "slug": "campaigns", "parent_id": "4feda7eb-2140-4f6e-be2c-09056509f675" }'{ "id": "c45d9d64-9663-4b5d-99be-d878b07a2b99", "model_key": "page", "site_key": "default", "parent_id": "4feda7eb-2140-4f6e-be2c-09056509f675", "name": "Campaigns", "slug": "campaigns", "path": "/blog/campaigns", "sort_order": 0, "created_at": "2026-10-07T09:18:00.260Z", "updated_at": "2026-10-07T09:18:00.260Z"}name and slug are required on both POST and PUT. A slug is lowercase letters and digits in hyphen-separated groups (campaigns, getting-started), unique among its siblings: a missing one is 422 folder_slug_required, a malformed one 422 folder_slug_invalid_format. parent_id is the parent folder’s id, or null (or absent) for the top level.
PUT replaces the folder’s name, slug, and parent all at once, so send the current parent_id to rename a folder in place: leaving it out moves the folder to the top level. sort_order is kept when omitted.
GET returns { "folders": [...], "entry_count": n }, with an entry_count on each folder too.
Moving entries returns { "folder_id": "…", "path": "/blog/campaigns", "moved": 2 }. moved counts entry documents, so an entry with two translations counts twice.
You can also set folder_id when creating or updating an entry. Note that PUT /api/v1/content/{entry_id} replaces the entry, so an update that leaves out folder_id moves the entry and its translations to the root. A new translation must go in its siblings’ folder (422 entry_folder_translation_mismatch); leave folder_id out and it inherits theirs.
Folder errors:
| Status | Code | Cause |
|---|---|---|
422 |
folder_site_key_required |
No ?site_key=. |
422 |
folder_name_required, folder_slug_required |
Missing name or slug. |
422 |
folder_slug_invalid_format |
Slug is not lowercase words joined by hyphens. |
409 |
folder_slug_taken |
A sibling folder already uses the slug. |
422 |
folder_parent_not_found |
parent_id names no folder in this tree. |
422 |
folder_parent_cycle |
Moving a folder inside itself. |
409 |
folder_delete_conflict |
Deleting would move a subfolder next to one with the same slug. |
404 |
folder_not_found |
No such folder. |
Rename or move a folder
Section titled “Rename or move a folder”Changing a folder’s slug or parent changes the path of every folder and entry beneath it, and so their URLs on your site. Redirect old URLs if they were public.
Renaming or moving a folder does not fire webhooks or record revisions on the affected entries. If your site caches pages by URL, rebuild or revalidate after reorganizing folders. Moving entries between folders (with Move to… or the move endpoint) fires entry.updated for each entry.
Delete a folder
Section titled “Delete a folder”Deleting a folder never deletes content. Its subfolders and entries move up to the deleted folder’s parent, and their paths change accordingly. For example, deleting /blog moves /blog/campaigns to /campaigns.
If a subfolder would land next to a folder with the same slug, the delete is refused with 409 folder_delete_conflict. Rename one of them first.
Related
Section titled “Related”- Entries & Publishing: entry slugs and updates.
- Localization: translations share a folder.
- Content API:
where:,filters, and$under. - Next.js blog example: routing a real site.