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.
Prerequisites
Section titled “Prerequisites”- 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
postmodel withtitle,excerpt,body, andpublished_datefields, as built in Blog with Next.js. Substitute your own model key and fields.
Set these environment variables; every example reads them:
export PLENARY_BASE_URL=https://your-instance.plenarycms.ioexport PLENARY_API_KEY=pln_pub_your_public_keyexport PLENARY_SITE_KEY=defaultexport PLENARY_LOCALE=en-usThe contract
Section titled “The contract”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:
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):
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 $:
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:
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 OKContent-Type: application/jsonX-Total-Count: 3An entry that does not exist (or is not published) is a 404:
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 FoundContent-Type: application/json
{"error":{"code":"entry_not_found"}}JavaScript with fetch
Section titled “JavaScript with fetch”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.
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);}node plenary.mjs3 of 3: [ 'getting-started', 'second-post', 'hello-plenary' ]Hello, Plenary 2026-10-01400 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.
Python with requests
Section titled “Python with requests”A complete module using requests (pip install requests). It pages through every post and shows a filter tree and error handling.
import jsonimport 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)python plenary_client.pygetting-started - Getting startedsecond-post - A second posthello-plenary - Hello, PlenaryHello, Plenary 2026-10-01['getting-started', 'second-post']404 entry_not_foundrequests 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.
Locale
Section titled “Locale”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.
Filtering
Section titled “Filtering”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.
Pagination
Section titled “Pagination”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”.
Images
Section titled “Images”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.
Errors and retries
Section titled “Errors and retries”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.
Caching
Section titled “Caching”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.
Related
Section titled “Related”- Content API: every parameter and error code.
- Authentication: public and private keys.
- @plenary/client: the same calls with types, if you use JavaScript.
- Forms API: submitting form entries over HTTP.