Skip to content

Without the SDK

You do not need the JavaScript SDK to use Plenary. The Content API is plain HTTPS and JSON: send a key in a header, ask for a model’s entries, and get JSON back. This page shows the whole contract with curl, then complete programs in JavaScript (fetch, no packages) and Python (requests) that you can adapt to any language.

  • A Plenary instance and its origin, for example https://your-instance.plenarycms.io. The API is under /api/v1.
  • A public API key (pln_pub_…) for your site, created under Access Management → API Keys. See Authentication.
  • A collection model with published entries. The examples use a post model with title, excerpt, body, and published_date fields, as built in Blog with Next.js. Substitute your own model key and fields.

Set these environment variables; every example reads them:

Terminal window
export PLENARY_BASE_URL=https://your-instance.plenarycms.io
export PLENARY_API_KEY=pln_pub_your_public_key
export PLENARY_SITE_KEY=default
export PLENARY_LOCALE=en-us

Every read follows the same rules:

Rule Detail
Endpoint GET /api/v1/content/{model_key} for a list (or a singleton’s one entry), GET /api/v1/content/{model_key}/{slug_or_id} for one entry.
Authentication The X-API-KEY: <key> header. Not Authorization: Bearer, which is for user tokens only.
Site and locale Send site_key and locale as query parameters on every request. Plenary does not fall back to another language.
Response JSON. A list is an array ([] when empty); a single entry or singleton is an object.
Errors A non-2xx status with {"error": {"code": "…", "vars": {…}}}. Branch on code.

The full parameter list is in the Content API reference.

List published posts, newest first:

Terminal window
curl -s "$PLENARY_BASE_URL/api/v1/content/post?site_key=$PLENARY_SITE_KEY&locale=$PLENARY_LOCALE&sort:data.published_date=desc&limit=10" \
-H "X-API-KEY: $PLENARY_API_KEY"
[
{
"id": "6d628320-97e5-4d0d-9376-37bd3d1a4ddb",
"site_key": "default",
"model_key": "post",
"slug": "getting-started",
"locale": "en-us",
"title": "Getting started",
"status": "published",
"published_at": "2026-10-07T09:12:53.765Z",
"publish_at": null,
"unpublish_at": null,
"created_at": "2026-10-07T09:12:48.4Z",
"updated_at": "2026-10-07T09:12:53.765Z",
"data": {
"body": "<p>Guide body.</p>",
"excerpt": "A guide in a folder.",
"published_date": "2026-10-04",
"title": "Getting started"
},
"folder_id": "5cbf4ecd-9dfe-4c66-9ae9-3e11ddc8f1f1",
"path": "/guides"
}
]

Get one post by slug (or by its id):

Terminal window
curl -s "$PLENARY_BASE_URL/api/v1/content/post/hello-plenary?site_key=$PLENARY_SITE_KEY&locale=$PLENARY_LOCALE" \
-H "X-API-KEY: $PLENARY_API_KEY"

Filter, sort, and return only some properties. Query parameter names contain : and $, so the easiest way to build the URL with curl is -G with --data-urlencode, single-quoting anything with a $:

Terminal window
curl -s -G "$PLENARY_BASE_URL/api/v1/content/post" \
-H "X-API-KEY: $PLENARY_API_KEY" \
--data-urlencode "site_key=$PLENARY_SITE_KEY" \
--data-urlencode "locale=$PLENARY_LOCALE" \
--data-urlencode 'where:data.published_date.$gte=2026-10-02' \
--data-urlencode "sort:data.published_date=desc" \
--data-urlencode "include=slug,title"
[{"slug":"getting-started","title":"Getting started"},{"slug":"second-post","title":"A second post"}]

Ask for the total match count with count=true; it comes back in the X-Total-Count header:

Terminal window
curl -s -D - -o /dev/null "$PLENARY_BASE_URL/api/v1/content/post?site_key=$PLENARY_SITE_KEY&locale=$PLENARY_LOCALE&limit=2&count=true" \
-H "X-API-KEY: $PLENARY_API_KEY"
HTTP/1.1 200 OK
Content-Type: application/json
X-Total-Count: 3

An entry that does not exist (or is not published) is a 404:

Terminal window
curl -s -i "$PLENARY_BASE_URL/api/v1/content/post/nope?site_key=$PLENARY_SITE_KEY&locale=$PLENARY_LOCALE" \
-H "X-API-KEY: $PLENARY_API_KEY"
HTTP/1.1 404 Not Found
Content-Type: application/json
{"error":{"code":"entry_not_found"}}

A complete script using only the built-in fetch (Node 18 or later, Deno, Bun, browsers, edge runtimes). Save it with an .mjs extension so top-level await works in Node.

plenary.mjs
const BASE_URL = process.env.PLENARY_BASE_URL;
const API_KEY = process.env.PLENARY_API_KEY;
const SITE_KEY = process.env.PLENARY_SITE_KEY ?? "default";
const LOCALE = process.env.PLENARY_LOCALE ?? "en-us";
class PlenaryError extends Error {
constructor(status, code, vars) {
super(`Plenary request failed (${status}): ${code}`);
this.status = status;
this.code = code;
this.vars = vars;
}
}
/** GET an API path, always sending site_key and locale. Throws PlenaryError on failure. */
async function plenaryGet(path, params = {}) {
const url = new URL(`/api/v1${path}`, BASE_URL);
url.search = new URLSearchParams({ site_key: SITE_KEY, locale: LOCALE, ...params }).toString();
const response = await fetch(url, { headers: { "X-API-KEY": API_KEY } });
if (!response.ok) {
const body = await response.json().catch(() => null);
throw new PlenaryError(response.status, body?.error?.code ?? `http_${response.status}`, body?.error?.vars);
}
return response;
}
// One page of posts from 2026, newest first, plus the total for pagination.
const response = await plenaryGet("/content/post", {
"where:data.published_date.$gte": "2026-01-01",
"sort:data.published_date": "desc",
limit: "10",
offset: "0",
count: "true",
});
const posts = await response.json();
const total = Number(response.headers.get("X-Total-Count"));
console.log(`${posts.length} of ${total}:`, posts.map((p) => p.slug));
// One post by slug.
const post = await (await plenaryGet("/content/post/hello-plenary")).json();
console.log(post.title, post.data.published_date);
// Errors come back as { "error": { "code": "...", "vars": { ... } } }.
try {
await plenaryGet("/content/post", { limit: "1000" });
} catch (err) {
console.log(err.status, err.code, err.vars);
}
Terminal window
node plenary.mjs
3 of 3: [ 'getting-started', 'second-post', 'hello-plenary' ]
Hello, Plenary 2026-10-01
400 entry_query_limit_exceeded { limit: 1000, max: 500 }

URLSearchParams percent-encodes the : and $ in parameter names, which the server accepts. Always set locale yourself: Node’s fetch sends Accept-Language: *, which Plenary ignores, so without locale you get the site’s default language.

A public key is safe in browser code. To call the API from a browser on another origin, nothing extra is needed: Plenary answers CORS preflights for every origin and allows the X-API-KEY header. Limit which origins may use a key with its Allowed origins setting.

A complete module using requests (pip install requests). It pages through every post and shows a filter tree and error handling.

plenary_client.py
import json
import os
import requests
BASE_URL = os.environ["PLENARY_BASE_URL"]
API_KEY = os.environ["PLENARY_API_KEY"]
SITE_KEY = os.environ.get("PLENARY_SITE_KEY", "default")
LOCALE = os.environ.get("PLENARY_LOCALE", "en-us")
class PlenaryError(Exception):
def __init__(self, status, code, vars=None):
super().__init__(f"Plenary request failed ({status}): {code}")
self.status = status
self.code = code
self.vars = vars or {}
def plenary_get(path, params=None):
"""GET an API path, always sending site_key and locale. Raises PlenaryError on failure."""
query = {"site_key": SITE_KEY, "locale": LOCALE, **(params or {})}
response = requests.get(
f"{BASE_URL}/api/v1{path}",
params=query,
headers={"X-API-KEY": API_KEY},
timeout=10,
)
if not response.ok:
try:
error = response.json().get("error", {})
except ValueError:
error = {}
raise PlenaryError(
response.status_code,
error.get("code", f"http_{response.status_code}"),
error.get("vars"),
)
return response
def all_posts(page_size=20):
"""Yield every published post, newest first, one page at a time."""
offset = 0
while True:
response = plenary_get(
"/content/post",
{
"sort:data.published_date": "desc",
"exclude": "data.body",
"limit": page_size,
"offset": offset,
"count": "true",
},
)
yield from response.json()
offset += page_size
if offset >= int(response.headers["X-Total-Count"]):
break
if __name__ == "__main__":
for post in all_posts(page_size=2):
print(post["slug"], "-", post["data"]["title"])
post = plenary_get("/content/post/hello-plenary").json()
print(post["title"], post["data"]["published_date"])
tree = {"where": {"$or": [{"slug": {"$eq": "second-post"}}, {"path": {"$under": "/guides"}}]}}
matches = plenary_get("/content/post", {"filters": json.dumps(tree), "include": "slug"}).json()
print([m["slug"] for m in matches])
try:
plenary_get("/content/post/does-not-exist")
except PlenaryError as err:
print(err.status, err.code)
Terminal window
python plenary_client.py
getting-started - Getting started
second-post - A second post
hello-plenary - Hello, Plenary
Hello, Plenary 2026-10-01
['getting-started', 'second-post']
404 entry_not_found

requests encodes the parameter names and values for you. The filters parameter takes the filter tree as a JSON string, so build it as a dictionary and pass it through json.dumps.

Every entry has a locale, and Plenary never falls back to another one: a post that exists only in en-us is a 404 when you ask for fr-ca. Send the locale parameter on every request, in lowercase or not (EN-US and en-us are the same). An invalid value such as locale=english! returns 400 entry_locale_invalid.

Fetching by id instead of slug ignores locale, because an ID already names one entry. See Localization.

Filters are query parameters named where:<field>.<operator>. Model fields are prefixed data.; built-in properties such as slug, status, and path are not. Conditions on different fields AND together.

You want Parameter
A specific slug where:slug=hello-plenary
Posts from 2026 on where:data.published_date.$gte=2026-01-01
Any of several slugs where:slug.$in=hello-plenary,second-post
Title contains “launch”, any case where:data.title.$ilike=launch
Posts with a cover image where:data.cover.$is_null=false
Everything in a folder and its subfolders where:path.$under=/blog
Either of two conditions filters={"where":{"$or":[…]}} (JSON)

Sort with sort:<field>=asc|desc; without one, results are newest-created first. Every operator, and which ones each field type accepts, is in Content API: Filters.

Use limit (default 100, maximum 500) and offset. To know when to stop, add count=true and read X-Total-Count, as all_posts does above. Do not request limit=0: it means “no limit”, not “no results”.

An image field’s value includes a variants map whose URLs are paths on your instance:

"cover": {
"media_id": "ce221afb-0ef2-4fc6-94d6-8c3da0cc391e",
"alt": "A blue gradient",
"variants": {
"card": { "url": "/media/ce221afb-0ef2-4fc6-94d6-8c3da0cc391e/8f3a10a3c8b42f06.webp" }
}
}

Join them with your base URL ($PLENARY_BASE_URL/media/…). No authentication is needed to fetch the file of a public asset.

Every error has the same body:

{ "error": { "code": "entry_query_limit_exceeded", "vars": { "limit": 1000, "max": 500 } } }
Status What to do
400 Fix the request; the code names the problem (for example entry_query_invalid for a filter that does not fit the model). Do not retry.
401 Check the key: authentication_required means no key was recognized (wrong header, or not a pln_ key); api_key_invalid means it is revoked, expired, or unknown.
403 permission_denied: the site_key names a site other than the key’s own. api_key_origin_not_allowed: a browser origin not on the key’s list.
404 model_not_found or entry_not_found. For a page lookup, render your not-found page.
429 rate_limited: the key’s per-minute limit. Wait and retry.
5xx Retry with backoff.

The full list is in Content API: Errors.

The API sends no caching headers, and a public key’s response for the same URL is the same for every visitor. Cache responses in your own layer (a CDN, a key-value store, or your framework’s data cache), and clear them when content changes by pointing a webhook at an endpoint of yours. Each webhook delivery names the model, entry ID, slug, and locale that changed. See Webhook events.