API Overview

ClearCMS provides a REST API for reading and writing your site's content, media, and forms. This page covers authentication, versioning, rate limits, and error handling — things that apply to every endpoint.

For specific endpoints, see:

• Headless API — pages and content items
• Media API — images, files, and folders
• Forms API — forms and submissions
• Design Tokens — branding values as CSS, JSON, or Tailwind config

Base URL

All API requests use your site's ClearCMS domain:

https://your-site.clearcms.app/api/v1

Replace your-site with your site's slug.

Versioning

The API uses a URL-based version prefix (/api/v1/). All current endpoints are v1. When breaking changes are introduced, a new version (v2) will be added alongside v1 — existing endpoints will continue to work.

Non-breaking additions (new fields in responses, new optional parameters) are made to the current version without a version bump.

Authentication

API keys

Most endpoints require an API key. Generate one in Settings > Developer > API Keys.

Include it as a Bearer token:

Authorization: Bearer YOUR_API_KEY

API keys have permission levels:

• Read — fetch content, media, globals
• Write — create and update content, upload media
• Admin — delete content, manage forms

Keep API keys secret. Never expose them in client-side JavaScript.

Public endpoints

Some endpoints work without authentication:

Endpoint	Description
GET /api/v1/public/content	Published content items
GET /api/v1/public/collections/{type}	Published collection items
GET /api/v1/public/pages/{slug}	Published page with sections
GET /api/v1/public/media	Media files (basic fields)
GET /api/v1/public/globals	Site settings
GET /api/v1/public/tokens.json	Design tokens as JSON
GET /api/v1/public/tokens.css	Design tokens as CSS
GET /api/v1/public/tailwind.config.js	Design tokens as Tailwind config
POST /api/v1/forms/{id}/submissions	Submit a form
GET /api/v1/schema	Schema introspection

Public endpoints support CORS and are cached (typically 60 seconds for content, 1 hour for tokens).

Rate limits

Requests are rate-limited per API key:

Tier	Requests per minute
Public (no key)	60
Free plan	120
Pro / Team	300
Business / Growth	600
Scale / Enterprise	1200

When you exceed the limit, the API returns 429 Too Many Requests with a Retry-After header (in seconds).

CORS

Public endpoints (/api/v1/public/*) allow cross-origin requests from any origin for all HTTP methods. Authenticated endpoints allow GET requests cross-origin. Write operations (POST, PUT, DELETE) on authenticated endpoints should be made from server-side code.

All endpoints respond to OPTIONS preflight requests.

Pagination

List endpoints use offset-based pagination:

GET /api/v1/public/content?type=posts&limit=10&offset=20

Every list response includes pagination metadata:

{
  "data": [...],
  "total": 42,
  "limit": 10,
  "offset": 20
}

Calculate pages:

const totalPages = Math.ceil(total / limit);
const currentPage = Math.floor(offset / limit) + 1;

The collections endpoint uses page-based pagination instead:

GET /api/v1/public/collections/posts?page=2&per_page=20

Filtering and sorting

Content list endpoints support:

Parameter	Example	Description
sort	createdAt	Field to sort by
order	desc	asc or desc
search	hello	Search in title field
filter[field][op]=value	filter[price][gte]=100	Field filtering (authenticated only)

Supported filter operators: eq, neq, gt, gte, lt, lte, like, in.

Draft content

By default, all endpoints return only published content. To include drafts, add ?draft=true and include an API key:

GET /api/v1/public/pages/about?draft=true
Authorization: Bearer YOUR_API_KEY

Error responses

All errors return JSON with this shape:

{
  "error": "NOT_FOUND",
  "message": "No page found with slug 'missing-page'"
}

Status	Code	Meaning
400	BAD_REQUEST	Invalid query parameter or request body
401	UNAUTHORIZED	Missing or invalid API key
403	FORBIDDEN	API key lacks permission for this operation
404	NOT_FOUND	Resource does not exist
422	VALIDATION_ERROR	Request body failed validation
429	RATE_LIMITED	Too many requests; check Retry-After header
500	INTERNAL_ERROR	Server error

SDKs

There are no official client SDKs yet. The API returns standard JSON and works with any HTTP client. See the Headless Quickstart for a practical Next.js example with a typed API client.