Clear CMS Docs 2026

The API

Read and write your site's content from your own code. The address, the main calls with examples, the limits and the errors.

On this page

The API lets your own code read a site's pages, records and files, save changes as drafts, and publish. It is what a website with its own code uses (a "headless" setup: Clear holds the content, your code draws the pages), and what a build script or another app uses. Everything is plain HTTPS and JSON.

Every change you send is saved as a draft, the same as an editor's change in the admin. Nothing reaches visitors until someone publishes.

Before you start

You need an API key: see API keys. Any key can read. To write, the key needs Save drafts, and Files, Pages and blocks or Delete when you use those.

The address

https://<site>.clearcms.app/admin-clear/api/v1/<site>/…

<site> is your site's id, the first part of its clearcms.app address. It appears twice: in the host and after /v1/. Use the site's clearcms.app address, even when the site has its own domain. In the examples below the site is example; put your own id in both places.

Five addresses need no key:

Address What it is
/admin-clear/api/v1 Where everything is: the API's version and the addresses below
/admin-clear/api/v1/openapi.json The full reference (OpenAPI 3.1), for tools that read it
/admin-clear/llms.txt A short guide written for AI assistants. Good for people too
/admin-clear/api/v1/llms.txt The same guide, next to the reference
/admin-clear/api/v1/version The admin's version

Sending the key

Put the key in the Authorization header of every call:

Authorization: Bearer clr_site_…

Call the API from a server or a build step when you can. It works from a browser too: every address answers the browser's permission check (CORS, a page on one site calling another) and sends Access-Control-Allow-Origin: *. But a key in a web page is visible to anyone who looks, so use a Read-only key there and nothing more.

A published read (a GET without draft=1) comes with an ETag and Cache-Control: private, max-age=60; send the ETag back as If-None-Match and the answer is 304 with no body when nothing changed. A draft read is never cached.

Your first call

Read the site: its record, its collections, what kind of site it is, and what your key may do here.

bash
curl -H "Authorization: Bearer $KEY" \
  https://example.clearcms.app/admin-clear/api/v1/example

The answer has:

  • record: the site record (name, menu, footer, contact, logo).
  • collections: each collection with its label and record count.
  • frontend.kind: blocks (a Clear Blocks site: pages are lists of blocks), own-blocks (your code draws its own block types) or own (your code decides every layout; only records can be changed).
  • languages, addons, and liveOnSave (collections the owner set to go live on save).
  • access: each permission of your key as true or false, with its limits. Read it before you write.

Records

List a collection

bash
curl -H "Authorization: Bearer $KEY" \
  "https://example.clearcms.app/admin-clear/api/v1/example/news?sort=-date&limit=50&fields=title,date"

The answer is { "total": 12, "records": [ … ], "next": null }. When next is not null there is another page: ask again with cursor=<next>.

Parameter Does
limit Records per page: 1 to 200, default 50
cursor The next value from the page before
sort A field name, or id, updatedAt. A - in front means newest or largest first: sort=-date. Without it, the collection's own order
fields Only these fields: fields=title,slug
ids Several records at once: ids=a,b,c
lang One language only, for fields that hold one value per language: lang=fr
draft draft=1 answers unpublished changes too. Needs Save drafts
page A page number, 1 first, instead of cursor. The answer then carries page and pages
where Keep the records that match a condition; repeat it for several, and all must match. See below
expand Relation fields whose records come back whole, under refs: expand=author,venue

Change sort or ids and start again without the cursor; an old cursor is refused with 400.

where takes a field name from the schema and one of these:

Condition Keeps records where the field…
year:2026 equals the value (or its list holds it)
year!:2026 does not equal it
town~toronto contains the words
date>=2026-01-01, date<=2026-12-31 is on or after, or on or before (dates and numbers)
photo: is empty
photo!: is set
bash
curl -H "Authorization: Bearer $KEY" \
  "https://example.clearcms.app/admin-clear/api/v1/example/events?where=date>=2026-11-01&where=town~toronto&page=1"

One record

bash
curl -H "Authorization: Bearer $KEY" \
  https://example.clearcms.app/admin-clear/api/v1/example/news/opening-day

Every record has the same shape:

json
{
  "id": "opening-day",
  "collection": "news",
  "data": { "title": "Opening day", "date": "2026-10-03" },
  "body": "Markdown text, or null",
  "updatedAt": "2026-10-03T14:00:00.000Z",
  "draft": false
}

data holds the fields; body holds the long Markdown text when the record has one. The site record is site/index. A page is a record in pages: { "title", "path", "sections": [ … ] }.

To find the record behind a page address: GET …/example/by-path?path=/about.

Drafts

Reads answer published content. Add ?draft=1 (needs Save drafts) to get unpublished changes instead; a record with an unpublished change comes back with "draft": true, and one deleted in a draft comes back with _deleted: true in its data.

bash
curl -H "Authorization: Bearer $KEY" \
  "https://example.clearcms.app/admin-clear/api/v1/example/search?q=sourdough&limit=20"

Text search over published records, title matches first. limit up to 100. The answer is { "records": [ … ] }.

The site's shape

GET …/example/schema lists every collection with its fields: each field's type, whether it is required, which values a select allows, and which fields hold one value per language. Writes are checked against it, so read it before you write. GET …/example/collections is the short version, names and counts.

The theme

GET …/example/theme is the site's look as the admin's Design page has it: every field (colours, fonts, corners, spacing, layout, motion, each block kind's design) with its kind, choices and limits, the values set now and the site's defaults. PATCH …/example/theme with { "values": { "colors.primary": "#2a6f4b", "roundness": "pill" } } sets some of them as a draft; null takes a value away so the site uses its default. Needs Pages and blocks. A value outside a field's choices is refused with 400 and error.allowed listing what is allowed. A site drawn by its own code without a theme form has none.

Writing

Save a draft

Change one field of a record. The key needs Save drafts.

bash
curl -X PATCH \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"data":{"title":"Opening day, now on Saturday"}}' \
  https://example.clearcms.app/admin-clear/api/v1/example/news/opening-day
  • PATCH changes only the fields you send and keeps the rest. PUT replaces the whole record.
  • The body is { "data": { … }, "body": "Markdown, optional" }.
  • An id that does not exist yet makes a new record.
  • A page's sections is one field: send the whole list back with your change in it.
  • The answer is the record as saved, with "draft": true. The change shows in the admin as a draft, and in History with the key's name as the author.

A write that does not fit the site answers 422 and lists every problem at once:

json
{ "error": { "status": 422, "message": "Some fields are not valid for this site", "fields": [
  { "field": "colour", "message": "Not a field of news" },
  { "field": "title.de", "message": "This site's languages are en, fr" }
] } }

Delete, restore, rename

  • DELETE …/example/news/opening-day marks the record deleted as a draft (needs Delete). The live record stays until someone publishes, and POST …/example/news/opening-day/restore takes the mark off.
  • POST …/example/news/opening-day/rename with { "id": "opening-weekend" } saves the record under a new id and marks the old one deleted (needs Pages and blocks). For a page, { "path": "/about/team" } changes its address and leaves a redirect from the old one.

Make a collection

POST …/example/collections with { "preset": "news" } makes a collection from a ready shape (GET …/example/collections/presets lists some sixty), or { "name": "Recipes" } makes an empty one. Needs Pages and blocks.

Preview a draft

Make a link that shows the site with its drafts. The key needs Save drafts.

bash
curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -H "Content-Type: application/json" \
  -d '{"path":"/","minutes":120}' \
  https://example.clearcms.app/admin-clear/api/v1/example/preview

The answer is { "url", "path", "expiresAt" }. Opening the link in a browser sets a cookie and shows the drafts on every page of the site. minutes is 1 to 1440, default 60. The link is listed, and can be turned off, under Settings → Share links in the admin.

If your own code draws the pages, it can take the link's last part, the token, and check it with POST …/example/preview/verify and { "token": "…" } (no key needed; answers { "valid": true }). Then send the token as an X-Clear-Preview header together with ?draft=1: that lets a read-only key read drafts for that visitor. A key is still required.

Files

List the site's files, as the admin's Media shows them:

bash
curl -H "Authorization: Bearer $KEY" \
  https://example.clearcms.app/admin-clear/api/v1/example/media

Each file has a name, folder, alt, width, height, sizeBytes, usedIn (which pages and records use it) and an address. Put the address in an image field.

Upload a file. The key needs Files.

bash
curl -X POST \
  -H "Authorization: Bearer $KEY" \
  -F "file=@loaves.jpg" \
  -F "folder=news" \
  -F "alt=Fresh loaves on the counter" \
  https://example.clearcms.app/admin-clear/api/v1/example/media

Photos (JPEG, PNG, WebP, GIF, AVIF, SVG) and PDFs up to 20 MB; videos (MP4, WebM, MOV) up to 50 MB; plain text files up to 5 MB. The answer is the file as listed above. Nothing shows on the site until a record uses its address and is published. DELETE …/example/media/<name> moves a file to the trash, where the admin can put it back.

Publish

bash
curl -X POST -H "Authorization: Bearer $KEY" \
  https://example.clearcms.app/admin-clear/api/v1/example/publish

Puts every draft live, like Publish now in the admin. The key needs Publish: a site or organization key with that switch on, or a personal key of an editor, admin or owner. Without it, you finish by pressing Publish in the admin. Send { "keys": ["news/opening-day"] } to publish only some drafts.

All addresses

Every address starts with https://example.clearcms.app/admin-clear/api/v1. In the last column, the switch the key needs; "none" means no key at all.

Call Does Needs
GET / Where everything is none
GET /openapi.json The full reference none
GET /llms.txt The guide for AI assistants none
GET /version The admin's version none
GET /sites The sites this key reaches Read
GET /example The site: record, collections, kind, access Read
GET /example/schema Every collection's fields Read
GET /example/collections Collections with record counts Read
GET /example/collections/presets Ready shapes for a new collection Read
POST /example/collections Make a collection Pages and blocks
GET /example/blocks The block types this site's pages can use; ?type=hero for one in full Read
GET /example/theme The theme: fields, values, defaults Read
PATCH /example/theme Set some theme fields, as a draft Pages and blocks
GET /example/<collection> List records Read
GET /example/<collection>/<id> One record Read
PUT and PATCH /example/<collection>/<id> Replace, or change some fields, as a draft Save drafts
DELETE /example/<collection>/<id> Mark deleted, as a draft Delete
POST /example/<collection>/<id>/restore Take the delete mark off Delete
POST /example/<collection>/<id>/rename New id, or a new page address Pages and blocks
GET /example/by-path?path=/about The record behind a page address Read
GET /example/search?q=… Search published records Read
GET /example/media The site's files Read
POST /example/media Upload a file Files
GET /example/media/<name> The file itself Read
DELETE /example/media/<name> Move a file to the trash Files
POST /example/preview A link that shows the drafts Save drafts
POST /example/preview/verify Is this preview token still good? none
POST /example/publish Put drafts live Publish
GET /example/forms/<id>/answers What people sent through a form Form answers
POST /example/email Send an email from the site, like a form's alert or thank-you Site key only: Save drafts sends to the site's own addresses, Send email to anyone. A key that only reads is refused

The reference at /admin-clear/api/v1/openapi.json has every parameter, body and answer in full.

Limits

  • 120 calls a minute per key, reads and writes together. Over it, 429 with Retry-After: 60. A key with Calls a day set answers 429 with Retry-After: 3600 when the day is used up.
  • A record is at most 1 MB (413 over it).
  • A list page holds at most 200 records; a search at most 100.
  • Uploads: 20 MB for a photo or PDF, 50 MB for a video, 5 MB for a text file, and the site's storage must have room.

Every call is recorded (which key, which site, which call, when) for the usage reports.

Errors

Errors are JSON with a plain message:

json
{ "error": { "status": 403, "message": "This key may not save drafts on this site" } }
Status Means
400 Something in the call is wrong: an unknown field in sort or fields, a cursor from another query, or a theme value outside its choices (error.allowed lists them)
401 No key, or the key is mistyped, revoked or past its end date
403 The key may not do this: wrong site, a switch that is off, a collection outside its list, or a live or test key on the wrong kind of site
404 No such site, collection or record
413 The record is over 1 MB
422 The fields do not fit the site's schema. error.fields lists each one
429 Too many calls. Wait for Retry-After seconds
503 The platform database is not connected. Try again shortly

For AI assistants

An assistant can use this API, but the MCP server is the easier road: the same content as tools, with the rules built in. See For AI assistants and What the tools do. The guide at /admin-clear/llms.txt is written for an assistant to read first.

Last updated October 23, 2026