Skip to content

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.

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.

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.

To serve /blog/campaigns/spring-sale, split the URL into the folder path and the last segment, then query both:

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

lib/get-page-by-url.ts
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:

lib/all-page-urls.ts
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.

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.

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

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.

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.