Skip to content

Content API

The Content API is how a site reads entries. It has two read endpoints under /api/v1/content: one returns a list of entries (or the one entry of a singleton), the other returns a single entry by slug or ID. Both take the same parameters for site, locale, field selection, and reference expansion; the list endpoint adds filtering, sorting, and pagination.

Every example on this page uses these placeholders:

Placeholder Meaning
https://your-instance.plenarycms.io Your Plenary instance’s origin. The API lives under /api/v1.
YOUR_API_KEY A public (pln_pub_…) or private (pln_prv_…) API key. See Authentication.
post A collection model key.
default, en-us A site key and a locale.

The SDK examples assume a client created like this (see @plenary/client):

lib/plenary.ts
import { createClient } from "@plenary/client";
export const plenary = createClient({
baseUrl: process.env.PLENARY_BASE_URL!, // e.g. https://your-instance.plenarycms.io
apiKey: process.env.PLENARY_API_KEY!,
siteKey: process.env.PLENARY_SITE_KEY ?? "default",
locale: process.env.PLENARY_LOCALE ?? "en-us",
});
Method Path Returns
GET /api/v1/content/{model_key} A collection model: a JSON array of entries. A singleton model: one entry object.
GET /api/v1/content/{model_key}/{slug_or_uuid} One entry, looked up by UUID or by slug.

Both require authentication: an API key in the X-API-KEY header (or the api_key query parameter), or a user access token in Authorization: Bearer. A public key reads only published entries; see Public key restrictions.

The same /api/v1/content prefix also carries the authenticated write endpoints the console uses (create, update, publish, delete, folders, revisions). They are not covered here, and public keys can reach none of them.

GET /api/v1/content/{model_key} on a collection model returns an array. It is always an array, even when nothing matches ([]).

Terminal window
curl -s "https://your-instance.plenarycms.io/api/v1/content/post?site_key=default&locale=en-us&sort:data.published_date=desc&limit=10" \
-H "X-API-KEY: YOUR_API_KEY"
const { items } = await plenary.listEntries("post", {
sort: { "data.published_date": "desc" },
limit: 10,
});

listEntries wraps the array as { items, total? }. total is present only when you pass count: true.

GET /api/v1/content/{model_key}/{slug_or_uuid} returns one entry object.

  • If the last path segment parses as a UUID, the entry is looked up by id and locale is ignored: an ID already names exactly one entry.
  • Otherwise the segment is a slug, matched together with the resolved locale (see Locale) and, when given, site_key.
Terminal window
curl -s "https://your-instance.plenarycms.io/api/v1/content/post/hello-plenary?site_key=default&locale=en-us" \
-H "X-API-KEY: YOUR_API_KEY"
curl -s "https://your-instance.plenarycms.io/api/v1/content/post/b08ce90c-e9b2-4555-8ee4-54d4ed0a1a40" \
-H "X-API-KEY: YOUR_API_KEY"
const bySlug = await plenary.getEntry("post", "hello-plenary");
const byId = await plenary.getEntry("post", "b08ce90c-e9b2-4555-8ee4-54d4ed0a1a40");

No match returns 404 with entry_not_found.

A singleton model has at most one entry per site and locale. GET /api/v1/content/{model_key} on a singleton returns that entry as an object, not an array.

Terminal window
curl -s "https://your-instance.plenarycms.io/api/v1/content/site_settings?site_key=default&locale=en-us" \
-H "X-API-KEY: YOUR_API_KEY"
const settings = await plenary.getSingleton("site_settings");

A singleton entry has "slug": null. When no entry exists for the site and locale, the response is 404 entry_not_found. Do not use the second endpoint for singletons: /content/site_settings/anything treats anything as a slug and returns 404.

The list-only parameters (where:, filters, sort:, limit, offset, count, q) are still validated on a singleton read, so a malformed value returns 400, but they do not change which entry comes back.

Every entry has the same intrinsic properties, plus data, which holds the model’s own field values keyed by field key. A real response:

{
"id": "b08ce90c-e9b2-4555-8ee4-54d4ed0a1a40",
"site_key": "default",
"model_key": "post",
"slug": "hello-plenary",
"locale": "en-us",
"title": "Hello, Plenary",
"status": "published",
"published_at": "2026-10-07T09:12:53.741Z",
"publish_at": null,
"unpublish_at": null,
"created_at": "2026-10-07T09:12:48.375Z",
"updated_at": "2026-10-07T09:16:41.112Z",
"data": {
"title": "Hello, Plenary",
"excerpt": "The first post on the new blog.",
"published_date": "2026-10-01",
"body": "<p>Welcome to the <strong>new blog</strong>.</p><h2>What is next</h2>",
"cover": {
"media_id": "ce221afb-0ef2-4fc6-94d6-8c3da0cc391e",
"alt": "A blue gradient",
"variants": {
"card": { "url": "/media/ce221afb-0ef2-4fc6-94d6-8c3da0cc391e/8f3a10a3c8b42f06.webp" },
"hero": { "url": "/media/ce221afb-0ef2-4fc6-94d6-8c3da0cc391e/87bc3720185cb993.webp" }
}
}
},
"folder_id": null,
"path": "/"
}
Property Type Description
id string (UUID) The entry’s ID. Stable for the life of the entry.
site_key string The site the entry belongs to.
model_key string The model’s key.
slug string | null URL segment. null on singletons. Translations of one entry share a slug.
locale string | null Lowercase locale tag, for example en-us.
title string | null Derived at read time from the model’s title field. You can select it with include, but not filter or sort on it; use data.<title field> instead.
status string published or draft. A public key sees only published, unless the key has Include draft content turned on.
published_at string | null When the entry was last published (RFC 3339, UTC).
publish_at string | null A scheduled future publish time, if set.
unpublish_at string | null A scheduled future unpublish time, if set.
created_at string RFC 3339, UTC.
updated_at string RFC 3339, UTC.
folder_id string | null The content folder holding the entry; null at the model root.
path string The folder’s directory path, for example /blog/campaigns; / at the root. It does not include the entry’s own slug.
data object Field values keyed by field key. See Field types for each type’s value shape.
draft object | null A published entry’s pending changes: { "data": …, "slug": …, "updated_at": … } while an edit waits to be published, else null. data and slug stay the live copy. Present for private keys and signed-in users only.

Field values come back as stored, with these read-time additions:

  • Image fields gain a variants map, { "<variant key>": { "url": "/media/…" } }, with one item per variant declared on the field. The URLs are paths on your instance: prefix them with the instance origin. Variants are generated in the background after a save, so a new variant URL can briefly fail until the file exists. An image whose media asset was deleted is flagged "missing": true and has no variants.
  • Blocks fields (Page Builder documents) gain a variant_url on Image blocks that set one-off size props. See Page Builder.
  • User fields return the stored ID together with a resolved profile (id, username, display_name, first_name, last_name, avatar_url). An ID that no longer names an account resolves to { "id": "…", "missing": true }.
  • Reference fields return a pointer, { "content_id": "…", "model_key": "…" }, unless you expand them with hydrate:.
Parameter Endpoints Description
site_key both Site to read from. See Site.
locale both Locale to read. See Locale.
where:<field>[.<op>] list One filter condition. Use several for different fields; they AND together. See Filters.
filters list A JSON filter tree with $and and $or. Replaces every where: parameter. See Filter trees.
q list Case-insensitive substring search over the title field and slug. See Search.
sort:<field> list asc or desc. Use several; applied left to right. See Sorting.
limit list Page size. Default 100, maximum 500.
offset list Number of matches to skip. Default 0.
count list true adds the total match count in the X-Total-Count response header.
include both Comma-separated list of the only properties to return. See Field selection.
exclude both Comma-separated list of properties to leave out.
hydrate:data.<field> both Expand a reference field. See Reference expansion.

Parameter names contain : and $. Most HTTP clients send them as they are and that works; if something in your stack rewrites them, percent-encode them (where%3Aslug.%24in=…). With curl, add -g when a URL contains [, ], {, or }, and quote URLs containing $ in single quotes or escape it.

site_key selects the site to read. Without it, the read spans every site the caller may read:

  • A public key is limited to the sites assigned to it. A site_key outside them returns 403 permission_denied.
  • A private key or signed-in user is limited to the sites its grants cover. A site_key outside them returns 403 permission_denied. A single entry on a site the caller cannot read returns 404 entry_not_found, so its existence is not revealed.

Send site_key on every request when your instance has more than one site. The SDK always sends it.

Every content entry has a locale. Lists are filtered to one locale, and a lookup by slug or a singleton read matches it exactly. There is no fallback to another language: a locale with no content returns 404 for a single entry and [] for a list.

The locale is resolved in this order:

  1. The locale query parameter.
  2. The first tag of the Accept-Language header. Only the first tag counts (en-US,en;q=0.9 means en-us); * and malformed values are ignored. Node’s built-in fetch sends Accept-Language: * by default, which falls through to the next step.
  3. The site’s default locale, when exactly one site is identified: an explicit site_key, or the site of the API key making the request.
  4. The instance’s default locale from configuration.

Locales are compared lowercase, so locale=EN-US and locale=en-us are the same. A malformed locale parameter returns 400 entry_locale_invalid.

Always send locale. The SDK sends it on every call.

A where:locale= condition is ANDed with the resolved locale, so it can only narrow the result. To read another language, change the locale parameter. See Localization.

A filter is a query parameter of the form where:<field>.<operator>=<value>. Without an operator, $eq is assumed.

?where:slug=hello-plenary
?where:data.published_date.$gte=2026-01-01
?where:data.title.$ilike=launch&where:status=published

<field> is a filterable intrinsic or data.<field_key> for a model field.

Filterable intrinsics Compared as
id, site_key, slug, locale, status, path, folder_id Strings.
published_at, created_at, updated_at Dates. Values may be RFC 3339 (with or without fractional seconds), YYYY-MM-DDTHH:MM[:SS], or YYYY-MM-DD. Any other form returns 400 entry_query_invalid.
has_draft true or false, with $eq only: whether a published entry has pending changes. Private keys and signed-in users only; a public key gets 400 entry_query_invalid.

title, model_key, publish_at, and unpublish_at cannot be filtered.

Conditions on different fields AND together. Repeating the same parameter (where:slug=a&where:slug=b) returns 400 entry_query_where_or_not_supported; use $in or a filter tree for OR.

Terminal window
curl -s 'https://your-instance.plenarycms.io/api/v1/content/post?site_key=default&locale=en-us&where:data.published_date.$gte=2026-10-03&sort:data.published_date=asc&include=slug,data.published_date' \
-H "X-API-KEY: YOUR_API_KEY"
[
{ "data": { "published_date": "2026-10-03" }, "slug": "second-post" },
{ "data": { "published_date": "2026-10-04" }, "slug": "getting-started" }
]
const { items } = await plenary.listEntries("post", {
where: { "data.published_date": { $gte: "2026-10-03" } },
sort: { "data.published_date": "asc" },
include: ["slug", "data.published_date"],
});
Operator Meaning Example
$eq Equal (the default) where:slug=hello
$ne Not equal where:slug.$ne=hello
$lt, $lte, $gt, $gte Less than, less or equal, greater than, greater or equal where:data.price.$lt=20
$in Value is in a set (comma-separated) where:slug.$in=a,b,c
$nin Value is not in a set (comma-separated) where:slug.$nin=a,b
$like Case-sensitive pattern match where:data.name.$like=Jo%
$ilike Case-insensitive pattern match where:data.name.$ilike=jo
$is_null true: the value is null or absent. false: it has a value. where:data.cover.$is_null=false
$under Folder subtree; path only where:path.$under=/blog

An unknown operator returns 400 entry_query_where_operator_invalid.

Pattern matching. $like and $ilike match a substring anywhere in the value: where:data.name.$ilike=o matches both “Jon” and “John”. In the pattern, % matches any run of characters, _ matches exactly one character, \% and \_ match the literal characters, and everything else is literal.

Typed values. A value for a data. field is converted to that field’s type before comparing. A value that cannot be converted, such as abc for a number field, returns 400 entry_query_invalid rather than matching nothing.

Field type Operators
text, rich_text, email, url, phone, color, select, computed, number, boolean, date, time, datetime All except $under
reference (single) $eq, $ne, $in, $nin (the value is the target entry’s ID), and $is_null
object, json, image, file, multi_select, list, tags, blocks, user, multiple references $is_null only

Any other combination returns 400 entry_query_invalid.

To find entries that point at a given entry through a reference field, match on the target’s ID:

?where:data.author=6d628320-97e5-4d0d-9376-37bd3d1a4ddb
?where:data.author.$in=6d628320-97e5-4d0d-9376-37bd3d1a4ddb,3f982d3b-6e46-4fda-9602-3eab4e2826dc
?where:data.author.$is_null=true

You cannot match on a property of the target (for example its title) in the same query. A reference field set to allow multiple values cannot be matched this way.

Entries live in per-model content folders. path is the folder’s directory path and never includes the entry’s own slug. To route a URL like /blog/spring-sale, split it into folder path and slug:

?where:path=/blog&where:slug=spring-sale

To fetch a whole subtree, use $under. It matches the folder and everything below it, and nothing else:

?where:path.$under=/blog

That matches /blog, /blog/campaigns, and /blog/campaigns/2026, but not a sibling folder named /blogroll. Do not use $like for this: where:path.$like=/blog% also matches /blogroll.

$under works only on path, and the value must start with /; anything else returns 400 entry_query_invalid. where:path.$under=/ matches every entry. For entries at the model root only, use where:path=/ or where:folder_id.$is_null=true.

For OR or nested logic, pass a JSON object as filters. It supports every operator above plus $and and $or, nested to any depth. In this form, $in and $nin take real arrays.

{
"where": {
"$or": [
{ "slug": { "$eq": "second-post" } },
{ "path": { "$under": "/guides" } }
]
}
}
Terminal window
curl -s -G "https://your-instance.plenarycms.io/api/v1/content/post" \
-H "X-API-KEY: YOUR_API_KEY" \
--data-urlencode "site_key=default" \
--data-urlencode "locale=en-us" \
--data-urlencode 'filters={"where":{"$or":[{"slug":{"$eq":"second-post"}},{"path":{"$under":"/guides"}}]}}'
const { items } = await plenary.listEntries("post", {
filters: {
where: {
$or: [{ slug: { $eq: "second-post" } }, { path: { $under: "/guides" } }],
},
},
});

When filters is present, every where: parameter in the same request is ignored. A filters value that is not valid JSON or does not match the schema returns 400 entry_query_filters_invalid. In the SDK, passing both where and filters throws before any request is sent.

q matches entries whose slug or title field contains the text, case-insensitively, ANDed with every other condition. It is meant for type-ahead pickers over one model, not full-text search.

?q=getting

The SDK has no q option. Use plain HTTP if you need it.

?sort:created_at=asc
?sort:data.published_date=desc&sort:data.title=asc

Sort on any filterable intrinsic or data.<field_key>, applied left to right. The direction must be asc or desc. Without a sort: parameter, results are ordered by created_at descending, newest first.

await plenary.listEntries("post", {
sort: { "data.published_date": "desc", "data.title": "asc" },
});

The SDK applies sort keys in object insertion order.

limit sets the page size (default 100, maximum 500) and offset the number of matches to skip. Add count=true to get the total number of matches, ignoring limit and offset, in the X-Total-Count response header. Counting costs an extra query, so it is off unless you ask for it.

Terminal window
curl -s -D - -o /dev/null "https://your-instance.plenarycms.io/api/v1/content/post?site_key=default&locale=en-us&limit=2&offset=0&count=true" \
-H "X-API-KEY: YOUR_API_KEY"
HTTP/1.1 200 OK
Content-Type: application/json
X-Total-Count: 3
const page = 2;
const pageSize = 10;
const { items, total } = await plenary.listEntries("post", {
limit: pageSize,
offset: (page - 1) * pageSize,
count: true,
});
const pageCount = Math.ceil((total ?? 0) / pageSize);

limit=0 is accepted and means no limit at all. Do not use it in delivery code.

X-Total-Count is exposed through CORS, so browser code can read it.

include returns only the named properties; exclude returns everything except them. Both take a comma-separated list. Sending both returns 400 entry_query_include_exclude_conflict (the SDK throws before sending).

Names may be any data.<field_key> or one of these intrinsics: id, site_key, model_key, slug, locale, title, status, published_at, created_at, updated_at, path, folder_id. Any other name, including publish_at and unpublish_at, returns 400 entry_query_include_field_invalid or entry_query_exclude_field_invalid.

Terminal window
curl -s "https://your-instance.plenarycms.io/api/v1/content/post?site_key=default&locale=en-us&include=slug,path" \
-H "X-API-KEY: YOUR_API_KEY"
[
{ "path": "/guides", "slug": "getting-started" },
{ "path": "/", "slug": "second-post" },
{ "path": "/", "slug": "hello-plenary" }
]
// A blog index does not need every post body.
await plenary.listEntries("post", { exclude: ["data.body"] });

With include, properties you do not name are absent, including id. If you include a data. field the caller may not see (a private field, for a public key), the response holds an empty data object rather than an error.

A reference field returns a pointer by default:

"conference": { "content_id": "bc5b8881-d9df-4ac5-afe7-041ea5faf82e", "model_key": "conference" }

hydrate:data.<field>=<selection> replaces the pointer with the target entry. The selection is a comma-separated list of properties (the names include accepts) or * for the whole entry.

Terminal window
curl -s "https://your-instance.plenarycms.io/api/v1/content/congregation?site_key=default&locale=en-us&limit=1&include=slug,data.conference&hydrate:data.conference=title,slug,data.name" \
-H "X-API-KEY: YOUR_API_KEY"
[
{
"slug": "advent-lutheran-church-westminster-co",
"data": {
"conference": {
"content_id": "bc5b8881-d9df-4ac5-afe7-041ea5faf82e",
"model_key": "conference",
"slug": "metro-west",
"title": "Metro West",
"data": { "name": "Metro West" }
}
}
}
]
await plenary.listEntries("congregation", {
hydrate: { "data.conference": ["title", "slug", "data.name"] },
});
await plenary.getEntry("congregation", "advent-lutheran-church-westminster-co", {
hydrate: { "data.conference": "*" },
});

Rules:

  • With an explicit selection, content_id and model_key are always added back, so you can still tell what the reference points at.
  • With *, the value is the full target entry, which carries its ID as id, not content_id.
  • Expansion is one level deep. References inside the expanded entry stay pointers.
  • Only single references expand. A reference field that allows multiple values returns its stored IDs.
  • A target the caller may not read (a draft for a public key, a private model, another site) stays an unexpanded pointer. No error is returned.
  • Naming a field that does not exist, or is not a reference, is ignored; the field comes back as stored.
  • The parameter must name a data. field (400 entry_query_hydrate_prefix_required), and each name in the selection must be selectable (400 entry_query_hydrate_field_invalid).
  • An expanded value is not valid input for a write. Expand only what you display.

A public API key is meant to be embedded in a site or app. Its access is fixed, and query parameters cannot widen it. Against the content endpoints it sees only:

  • Published entries, as they are live. Draft entries are absent from lists and return 404 by slug or ID, and a published entry’s pending changes are not in the response (draft is always null). A key with Include draft content turned on (for preview builds) also reads draft entries, and reads a published entry’s pending data and slug in place of the live ones, which is the content a publish would make live; it still never sees draft itself, and every other rule still applies.
  • Models not marked private. A private model returns 404 model_not_found, the same as a model that does not exist.
  • The key’s own sites. A site_key outside them returns 403 permission_denied.
  • Fields not marked private. Private fields are removed from data, and naming one in where:, sort:, or hydrate: fails as an unknown field (400 entry_query_invalid), so its value cannot be probed.

A where: condition on status, site_key, or locale is ANDed with these rules and can only narrow the result.

Private keys and signed-in users holding content:entries:read see drafts, private models, and private fields in full, within the sites and models their grants cover. See Permissions.

Situation Status Body
List 200 JSON array of entries ([] when nothing matches)
Singleton or single entry 200 JSON entry object
Any error 4xx or 5xx { "error": { "code": "…", "vars": { … } } }
Header When
Content-Type: application/json Every response.
X-Total-Count List requests with count=true.
Access-Control-Allow-Origin Requests that carry a browser Origin. Every origin’s preflight is answered, with X-API-KEY among the allowed headers. To limit which origins may use a particular key, set the key’s Allowed origins.

The API sends no Cache-Control, ETag, or Last-Modified headers. Cache in your own layer and invalidate with webhooks; see Instant revalidation.

Content reads have no instance-wide rate limit. An API key can carry its own Rate limit (requests per minute); a request over it returns 429 rate_limited until the minute rolls over. A key without a limit is unlimited. See API keys.

The error body is always { "error": { "code": "<code>" } }, plus a vars object when the code has details. Match on code, not on the HTTP status alone.

{ "error": { "code": "entry_query_limit_exceeded", "vars": { "limit": 501, "max": 500 } } }
Status Code Cause
400 entry_locale_invalid locale is not a valid locale tag.
400 entry_query_where_operator_invalid Unknown operator. vars.param names the parameter.
400 entry_query_where_field_invalid A where: field that is neither a filterable intrinsic nor data.…. vars.field.
400 entry_query_where_or_not_supported The same where: parameter appears twice. vars.param.
400 entry_query_filters_invalid filters is not valid JSON or does not match the schema.
400 entry_query_invalid The query does not fit the model: unknown data. field, operator not allowed for the field type, value not convertible to the field’s type, malformed date, $under misused, or has_draft from a public key.
400 entry_query_sort_field_invalid Sort on an invalid field name. vars.field.
400 entry_query_sort_direction_invalid Direction is not asc or desc. vars.field, vars.direction.
400 entry_query_sort_duplicate The same sort: parameter appears twice. vars.param.
400 entry_query_limit_invalid limit is not a non-negative integer.
400 entry_query_limit_exceeded limit is over 500. vars.limit, vars.max.
400 entry_query_offset_invalid offset is not a non-negative integer.
400 entry_query_count_invalid count is not a boolean.
400 entry_query_include_field_invalid, entry_query_exclude_field_invalid A name that cannot be selected. vars.field.
400 entry_query_include_exclude_conflict Both include and exclude were sent.
400 entry_query_hydrate_prefix_required A hydrate: parameter that does not name a data. field. vars.field.
400 entry_query_hydrate_invalid The same hydrate: parameter appears twice. vars.field.
400 entry_query_hydrate_field_invalid A name in the hydrate selection cannot be selected. vars.field.
401 authentication_required No credential, or an X-API-KEY value that does not start with pln_pub_ or pln_prv_.
401 api_key_invalid The key is unknown, inactive, revoked, or expired.
401 token_invalid A user access token is malformed or expired.
403 api_key_origin_not_allowed The browser Origin is not in the key’s allowed origins.
403 permission_denied site_key is outside the caller’s sites, or the caller may not read this model.
404 model_not_found No content model has this key, or it is private and the caller is a public key.
404 entry_model_not_content The key names a form or another non-content model. Forms have their own API; see Forms API.
404 entry_not_found No entry matches the slug or ID in the resolved locale and site, or a public key asked for a draft.
429 rate_limited The key’s per-minute limit is used up.
500 internal_server_error Unexpected server failure. Safe to retry.

The SDK throws these as typed errors: PlenaryNotFoundError (404), PlenaryForbiddenError (403), PlenaryValidationError (400 and 422), and PlenaryError for everything else. Each carries status, code, and vars.

import { PlenaryNotFoundError } from "@plenary/client";
import { plenary } from "./plenary";
export async function findPost(slug: string) {
try {
return await plenary.getEntry("post", slug);
} catch (err) {
if (err instanceof PlenaryNotFoundError) return null;
throw err;
}
}

See Errors for codes from every endpoint.