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.
curl -H "Authorization: Bearer $KEY" \
https://example.clearcms.app/admin-clear/api/v1/exampleThe 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) orown(your code decides every layout; only records can be changed).languages,addons, andliveOnSave(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
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 |
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
curl -H "Authorization: Bearer $KEY" \
https://example.clearcms.app/admin-clear/api/v1/example/news/opening-dayEvery record has the same shape:
{
"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.
Search
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.
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-dayPATCHchanges only the fields you send and keeps the rest.PUTreplaces the whole record.- The body is
{ "data": { … }, "body": "Markdown, optional" }. - An id that does not exist yet makes a new record.
- A page's
sectionsis 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:
{ "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-daymarks the record deleted as a draft (needs Delete). The live record stays until someone publishes, andPOST …/example/news/opening-day/restoretakes the mark off.POST …/example/news/opening-day/renamewith{ "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.
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/previewThe 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:
curl -H "Authorization: Bearer $KEY" \
https://example.clearcms.app/admin-clear/api/v1/example/mediaEach 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.
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/mediaPhotos (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
curl -X POST -H "Authorization: Bearer $KEY" \
https://example.clearcms.app/admin-clear/api/v1/example/publishPuts 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,
429withRetry-After: 60. A key with Calls a day set answers429withRetry-After: 3600when the day is used up. - A record is at most 1 MB (
413over 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:
{ "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.